{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Multi-armed bandits"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "River has a `bandit` module. It contains several multi-armed bandit policies, bandit environments, and utilities to benchmark policies on bandit problems.\n",
    "\n",
    "Bandit environments in River implement the [Gym](https://www.gymlibrary.dev/) interface. You can thus load them with `gym.make`. Note that Gym is intended for reinforcement learning algorithms, while bandit policies are the simplest form of reinforcement learning. Bandit policies learn by receiving a reward after each step, while reinforcement learning algorithms have to learn from feedback that may arrive at the end of a (long) sequence of steps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:47:28.911688Z",
     "iopub.status.busy": "2023-12-04T17:47:28.909441Z",
     "iopub.status.idle": "2023-12-04T17:47:28.986844Z",
     "shell.execute_reply": "2023-12-04T17:47:28.986570Z"
    }
   },
   "outputs": [],
   "source": [
    "import gymnasium as gym\n",
    "\n",
    "for k in gym.envs.registry:\n",
    "    if k.startswith('river_bandits'):\n",
    "        print(k)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "River's bandit module offers the `bandit.evaluate` function to benchmark several policies on a given environment. It takes as input a list of bandit policies, a bandit environment (the problem to solve), and a reward object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:47:28.988524Z",
     "iopub.status.busy": "2023-12-04T17:47:28.988444Z",
     "iopub.status.idle": "2023-12-04T17:47:29.404060Z",
     "shell.execute_reply": "2023-12-04T17:47:29.403703Z"
    }
   },
   "outputs": [],
   "source": [
    "import gymnasium as gym\n",
    "from river import bandit\n",
    "import pandas as pd\n",
    "from tqdm import tqdm\n",
    "from river import stats\n",
    "\n",
    "policies=[\n",
    "    bandit.EpsilonGreedy(epsilon=0.1),\n",
    "    bandit.EpsilonGreedy(epsilon=0.01),\n",
    "    bandit.EpsilonGreedy(epsilon=0),\n",
    "]\n",
    "\n",
    "env = gym.make(\n",
    "    'river_bandits/KArmedTestbed-v0',\n",
    "    max_episode_steps=1000\n",
    ")\n",
    "\n",
    "trace = bandit.evaluate(\n",
    "    policies=policies,\n",
    "    env=env,\n",
    "    reward_stat=stats.Mean(),\n",
    "    n_episodes=(n_episodes := 2000),\n",
    ")\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `bandit.evaluate` function returns a generator containing the results at each step of the benchmark. This can be wrapped with a `pandas.DataFrame` to gather all the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:47:29.405926Z",
     "iopub.status.busy": "2023-12-04T17:47:29.405781Z",
     "iopub.status.idle": "2023-12-04T17:47:59.938410Z",
     "shell.execute_reply": "2023-12-04T17:47:59.938118Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  0%|                                                                                                                                                                   | 0/6000000 [00:00<?, ?it/s]/Users/max/Library/Caches/pypoetry/virtualenvs/river--dXL33ck-py3.11/lib/python3.11/site-packages/gym/utils/passive_env_checker.py:233: DeprecationWarning: `np.bool8` is a deprecated alias for `np.bool_`.  (Deprecated NumPy 1.24)\n",
      "  if not isinstance(terminated, (bool, np.bool8)):\n",
      "100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 6000000/6000000 [00:25<00:00, 236810.21it/s]\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>episode</th>\n",
       "      <th>step</th>\n",
       "      <th>policy_idx</th>\n",
       "      <th>arm</th>\n",
       "      <th>reward</th>\n",
       "      <th>reward_stat</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>1324896</th>\n",
       "      <td>441</td>\n",
       "      <td>632</td>\n",
       "      <td>0</td>\n",
       "      <td>2</td>\n",
       "      <td>0.226086</td>\n",
       "      <td>0.499848</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3566176</th>\n",
       "      <td>1188</td>\n",
       "      <td>725</td>\n",
       "      <td>1</td>\n",
       "      <td>6</td>\n",
       "      <td>2.363962</td>\n",
       "      <td>0.935468</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1109043</th>\n",
       "      <td>369</td>\n",
       "      <td>681</td>\n",
       "      <td>0</td>\n",
       "      <td>5</td>\n",
       "      <td>2.780757</td>\n",
       "      <td>1.467402</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4286042</th>\n",
       "      <td>1428</td>\n",
       "      <td>680</td>\n",
       "      <td>2</td>\n",
       "      <td>1</td>\n",
       "      <td>2.039255</td>\n",
       "      <td>1.603312</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5395174</th>\n",
       "      <td>1798</td>\n",
       "      <td>391</td>\n",
       "      <td>1</td>\n",
       "      <td>8</td>\n",
       "      <td>1.625523</td>\n",
       "      <td>1.232745</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         episode  step  policy_idx  arm    reward  reward_stat\n",
       "1324896      441   632           0    2  0.226086     0.499848\n",
       "3566176     1188   725           1    6  2.363962     0.935468\n",
       "1109043      369   681           0    5  2.780757     1.467402\n",
       "4286042     1428   680           2    1  2.039255     1.603312\n",
       "5395174     1798   391           1    8  1.625523     1.232745"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trace_df = pd.DataFrame(tqdm(\n",
    "    trace, position=0, total=(\n",
    "        n_episodes *\n",
    "        len(policies) *\n",
    "        env._max_episode_steps\n",
    "    )\n",
    "))\n",
    "trace_df.sample(5, random_state=42)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is then straightforward to plot the average reward each policy obtains at each step, by averaging over episodes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:47:59.940573Z",
     "iopub.status.busy": "2023-12-04T17:47:59.940435Z",
     "iopub.status.idle": "2023-12-04T17:48:00.781440Z",
     "shell.execute_reply": "2023-12-04T17:48:00.770622Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Axes: xlabel='step'>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAiMAAAGwCAYAAAB7MGXBAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy81sbWrAAAACXBIWXMAAA9hAAAPYQGoP6dpAACz00lEQVR4nOydd3wT5R/HP1lNd0spnbS0rLL3HsooeyOKorJRBBR+oAIqG8QFsvdSEQERlL3KhrL3XoVC997N/v1xTXKXXFZXgH7fr1dfTS7P3T1J03s+950CjUajAUEQBEEQhJ0Q2nsCBEEQBEGUbUiMEARBEARhV0iMEARBEARhV0iMEARBEARhV0iMEARBEARhV0iMEARBEARhV0iMEARBEARhV8T2noA1qNVqxMbGws3NDQKBwN7TIQiCIAjCCjQaDbKyshAQEACh0LT947UQI7GxsQgKCrL3NAiCIAiCKAQvXrxAxYoVTb7+WogRNzc3AMybcXd3t/NsCIIgCIKwhszMTAQFBenWcVO8FmJE65pxd3cnMUIQBEEQrxmWQiwogJUgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIgCLtCYoQgCIIg7EyeMs/eU7ArJEYIgiAIwo6ciTmDZn82w293frP3VOwGiRGCIAiCsJITL05g6MGhiMmOKbZjfnvmWwDAL5d/KbZjvm6QGCEIgiBeC24l3cKD1Ad2ncPnxz7HlYQrmHFuRrEdUyKUFNuxXldIjBAE8VpzKf4S1t9aD7VGbXLMxbiLWHptKVRqVSnOjChOMmQZGLR/EAbsGWD2b22JaWen4Z3d70CmkhVpPil5KTaPP/L8CBRqhdFrDiKHIs3lTYDECEEQrzXDDw3HoquLEBEdYXLMiMMjsObmGvz7+N/SmxhRrCTlJuke8y3obPhEZ4YsA5fiL+Hfx//iYdpDnHl5BmqNGvuf7seLrBfFPl8AWHVjFd7f+z5yFDn4cP+HmHhiInY+3Gk0zkFoXoxkyjPfeCFNYoQgiDeCmCzLPvznWc9LYSbWcT7uPBZeWWhxYS0OLsRdQFRGVImfp7hRqpWYd34eDj87DJVGvxibs2rsfrIbLf9qiXOx5zjbP9r/EYYfGq57rlArsPvJbkw+PRndd3a3eW7WWGeWX1+OOyl3sPPRTl2Myfm480bjzFlG4nPi0fqv1vj0yKc2z9EQjUaD9Pz0Ih+nJCAxQhDEa4O5u0OxUGxxf41GU5zTKRKjDo/Cxtsbee+UbUGpViI+J97k64/SHmHk4ZHo/W/v1+ruWq6SY+75udj6YCsmnZzEEW1yldzkft+e+RZ5yjyMPzaes/1Z5jPOc7VGjUvxl8zO4edLP2PdrXW8r2nAfJcORh1Eh+0dcD3xuu61g1EHcSbmjO55hixD9zjUI9ToWBKRPmbE8Du6P2o/AOBC/AWzc7WGb858g7bb2uJa4rUiH6u4ITFCEMRrQXJeMtptb4f5F+bzvm5KjJx6eUr32JIYeZj20Ky7pyR4mf2ySPuPixiHTjs6mVxY76fe1z1ut70dkvOSka/Mt2iRUaqVRZqXNdxPvY8MWQbupNzB6COjOcGpM87NwD+P/tE9Z9fhMCdGtFiyXCjUCggFppfA55nP8fvd37H46mLeY2m/S1+d+gpJeUn4+MDHeJz2GLHZsfjq1Ff47OhnurHJecm6x84SZ6NjsQNYDa0+bBeOQmX+bxabHYuLcRdNvr736V4AwPpb680exx7YLEZOnTqFXr16ISAgAAKBAP/++6/V+549exZisRgNGjSw9bQEQZRxfr/zO9Jl6dhyf4tuG3tB5RMjD9MeYmzEWN1zNcwvUO/sfgcTjk/AjaQbxTBj6xBAUOh9V95YibOxZwEAf93/i3cM272RLkvHptub0GF7B3yw9wOTx414HoEWW1rg8LPDAIA7KXfQ99++OPniZKHnasj1xOt4d8+76LWrF0YcGoGzsWcx4vAI3evahVOLrWLEEtmKbIgEIpOvs0UBn1voWeYzbLy9kbOt3+5+vFYq9v58gkIs0H93sxXZusd5yjz8eOlH3fNLCZcw+dRkPE57DICJJdGKou0PtqPLP10w4vAIjpWGD3MizF7YPKOcnBzUr18fy5cvt2m/9PR0DB48GB07drT1lARBWCBfmY/I2EiLd0724HridSy5usRoAVGoFIiIjuCYsM3BdyfPXqD40iOfZTzjPLfWTXM/5b7FMfnKfFxJuIJ8ZT623d/Gm3IqV8lxNeGqWSuDQFA4MfI47TFWXF+he27qvRluv5t6F1mKLDxIe2DSejDhxATIVDJMOjkJADD+2Hg8yXiCccfGIV+Zrxt36NkhdP2nK24n3zY6RnxOvFk3yMmXjLBJk6UhR5EDQO/O4Pu8cpW5uscLLi9AriLXaAz7u2Tpc82UZ5odI2QtjzIlf4zKwisLjbbxCRf2tl2Pd2HVjVWYEzlH97dhv/4i6wW67+yOtTfXGom/T498iv1R+zEmYgyuJV5D679ao97v9XAj6QbmnJ+jG3c54bLJ9wUUTQCXFDaLkW7dumHu3Lno16+fTfuNHj0agwYNQsuWLW09JUEQFvjmzDf45MgnvBdHe/PxgY+x9tZa/H73d8725deXY8LxCRhzdAxnu0qtwmdHP8MPF3/gbOdboNgLI9/CYihQTC2+GbIMThCjUsM9V74yH+fjznPE3jdnvsHQg0Mx7OAwzL0wFwP2DECGLAM7Hu7A+3vfR3xOPGZFzsKQg0M4okH7HrWYuzs3JDU/VbdwpcnSTL63ky9OIjozmvc9s59bW4I8JV+fxtr0z6a4HH8Zao0aX578EjHZMUZxFXKVHEMPDsXwQ8NxJeGKbvvep3sx9/xcqNQqswtiuizdaNu9lHu6xydensCqm6uMxrAXZJVGhc13N+PQs0O858iWcy0jhqKNbVHKV+XDWvisNlqxBQBxOXFYfn05tj/cjueZTEA1W4ysubkGL7JeYMm1Jfjq1Fe854jLicOCywt0zz/a/xHndUs3JUKBUDfPPGUenqQ/sfCuSp5SsdVs3LgRT58+xYwZ1hWJkclkyMzM5PwQRFnkQeoDi0F2AHDk+REAwOZ7m60+tlwlx6mXp3jvMEuCh6kPdY/zlflYf5vxW99MvskZdznhMs7EnMGf9/7UbVOpVRYtI3xihR0YCOiDDg3Z/mA7J73T8Fg/X/oZow6PwsobK3XbtJ/57RS9VeDbM99iVuQs3Em5g20PtmH3k90AgA23N3COx77Lt9Yykpqfire3vY1+/zE3goZCQg01lGoltj/YjnHHxqHHrh667WzYiyV7kTSHYeDrmIgx6PR3J93ziOgIfLD3A12mxuWEy7rskT1P9ujGTT09FdsebMOR50fMugrS8tOMthl+hndT7gJgLBxa2MJDqVbix0s/4suTX/JmEmXJsziCSCs4NBoNLsVf4tQR0YpevnkZwveZWtqP/be0NrvKXEbRxjsbOXEqhpyNPYvmfzbHulvr0OzPZuj7X19ciCt6gGxRKHEx8ujRI0yZMgWbN2+GWGw52h0A5s+fDw8PD91PUFBQCc+SIF49NBoNBuwZgOGHhpu9sBSWny/9jLERYzErcpbFsfuf7jdKlbQVtrXhg32m4xXYPnelWgmVWoV3977LCWbUwr6I891NG2LKMiJXG7iQDBaE7Q+3AwDW3lpr9vha1wMAuEhcdI8dxY4AmLTODts74EDUAYtzMuRqwlUAjBlfrVEbvV+NRoOFVxZyrAO5ilyo1dzjZ8mzdI8NF06NRsO7mBqKuDxlHhLzEjnbbqfcxr6ofUbn4IuhiM+JNytGrP1b/nX/L7T+qzX2PNljNmWVr3T7sRfHOMG92u/S7ie7MfzQcHx6VJ9KK1PJcCvpFt7a9pbFebFjPrSk5qfyjh16cCiGHhzKyfSxVHNEi7mbiDxlHqacmmL2daVGicVXF+u28f1/lSYlKkZUKhUGDRqEWbNmoXr16lbvN3XqVGRkZOh+XrwomYI0BPEqk5SnL/JkbVwFHw9SH+Dvh38bmaG3PtgKQJ86aIoXWS8w+fRkTp2Da4nXdEFyMdkxFgPmAK614XH6Y94xKrUK3539Tvc8T5mH2JxYPEp7xDueLUZ+vfIrtj/Yznnd0FxtauE33G4pk8Sau1f2GCexEwAmnTcpL4kjGLR33ZZECbsWxbHoY0Z32xpo8MfdPzjbHqU/MhJa7IU+Q5aBrfe3IjGXERYzzs1A261tLb01s5yPO48vT36pe87nCpKr5WYtQtZYIFRqFb6/8D0AxmXGDlQ2hE8MZMgycD3puu55riIXj9Me4+fLPxuN/fHSjxi0f5DFOQFcS40WU+8nJT+F48ayhbicOLOvX4i/gPf2vIdVNxh3lqV4KXunfZeoGMnKysLly5cxbtw4iMViiMVizJ49Gzdu3IBYLMaxY8d495NKpXB3d+f8EMSbzpWEK9j3dJ/uOdttUJTy1wP2DMDsyNmcu/Fj0fz/e3xwKl+qFMiQZWDwgcH4+MDHiMuOQ9d/uuoeG3IuRm9NUaqVyFfmm009ZN9RA8xCZi62wHChY1smAK4LBTBt2ja8UGvFyM2km/j9DjfW5eCzg2i5xXLsGztOJDkvGdly4ztmgHEP/HH3DzTe3Bjzzs/TBd0qVAp8ffJr/POQuWNlWyz+d+J/uJd6j3Mcvu9ISl6K0Xtmi5GtD7Zi3oV56Pg3k1iw6/GuIhVhy5BlYNThUUbvz3D+cpWcEyBqiDWWkQdp3IBhQ3cfm9Q8fssEm4vxF9Fvdz9e4W+Nq1SL4XcYMLa82bo/H9b8ne6l3sPy68vxIvOFRYHNjpGxB9b5TQqJu7s7bt26xdm2YsUKHDt2DDt27EBoqHHxF4J4XdBoNMhWZMPNwa1Yjjf04FAAQPVy1VGtXDW8zNLXn7DlYmaKW8m30CWkC4QCIcYf1xeE8pR6mt2PbaLPUeTgUbreStH5n866xzHZMTgdcxpb7m3BivAVuJF0A1+f+lr3ulKtxE+XfsLfD/82ea4cJddFkKfMM3uRNBQjqXmpuJJwBQ19GiIuJw5rbq7hvM4nRuaen4ttD7Zxtmkv3B/u/9Bo/Fcn+YMKLdHyL34Bk6PIwU+XfgLAiIOtD7bi1pBb2PN0Dw48O4ADzw6gqV9To0WKLVwB/jvfQ88Owd3B9M3cjUR9CrPh8QoDX7+WfGU+Vt5YyRFnCrUC0VnRJo9jjRixNt4FMO0mYVNcje8epj20PMgMbGsNH+Wk5YyCly3xzp53EPGu+fo5EdERyJZnw9XB1aZjFxc2W0ays7Nx/fp1XL9+HQAQFRWF69evIzqa+WJNnToVgwcPZg4uFKJOnTqcHx8fHzg6OqJOnTpwcXExdRqCeOWZfHoyWv3VCk/Tn5oc8+e9P9Hvv344+Owguv7TFbMjZ2PM0TEcawPAXUi0Pna2aZcvOl6pVmLdrXW4mcS9IxxzdAzv3VWeMg99/+uLkYdHcrYbipE7yXcw9fRUnZ+dndaYrcg2ebGVqWSYc34OnmQ8wcIrC40C4lQalVkhAsDIepCnzOPNTtAWJjMUI7dTbmPowaGYdnYauv7T1Wi/i3EXIVPJoNFokKvIRYYsw0iIAMUj/qyFbbHSolKrOAto739785r/2fBZRvZH7de54ywx5bTpGANrYVcd1ZKcl2yUTbTh9gbe962FnSVVHLCzgUoavs+gOKniWcXmffKUebiVfMviOEPLYmlisxi5fPkyGjZsiIYNGwIAJk6ciIYNG2L69OkAgLi4OJ0wIYjXnSfpT/DN6W90KXhstBfTP+79YfSalh8u/oDH6Y/x1cmvEJMdg78f/o3TMaex6Ooizjj24qfNAMlS6AUF34K858keLL662Oju/XTMaWy8vRFp+WmcTIbridfxLPMZLsZz3STsjJMpp6fg/X3vY+/Tvej7b18AXGtF/939ORklbNgZIumydKNAPqVaCUeRI+++Wgz30dbxMGTC8Ql4mfXSZGqqNovFkDRZGr478x1mRc5C8y3NcTrmNO+4P+7+YVVgb1Fo6W/a1dN9Z3eOFUelUVkWI1Db3IpeGyti9rg2uAhjc2KNtlmatyE3k25yMqlsZVTdUUbbrLGMvC4EuwebfX1Y7WG82y31thEKhOgaYizgSwub3TTt2rUzGwizadMms/vPnDkTM2fOtPW0BGEXhhwcggxZBu6l3sOuPrt4xxherBUqBSQiidlod7Zf+u+Hf2PVdX3NBG01RrYZWqaSYem1pdj3dB82d98Mbydv3gwBLSn5KRgXMY7jR3+SwV9LQKPR4Gn6U3hIPTim+nxVPmQqGafTbZ4yz6QAYNeBUKgURlaOq4lXTc5Xi6Hp/YeLP2BIrSG8Y/v918+m+g9aDj47qHs89fRUk+N2PNxh9ji+zr5IyE2w+fy6/V18Tb4WmxOrCzzUok1ldRI78f4NCpOaaY0FyJxgGVp7KDbd2WTzec3B5xorKq+6GOmgFMEnNx1b3S27fNlut+HpGdjg6cF5vXtAW2y8s9FwN4tEvBsBkdD6mjfFzatXE5YgCsmeJ3sw+uhom+/E+HiR+QJ5yjydaHic/hhx2XEYeXgkTr44ybnwswPDZkXOQvu/2+Nm0k1OXIYhJ1+e1AWRzo6czUmT1MZIsBdzuVqONTfXICY7BlvvM2b3co7lTB5fAIHZgD42j9Mfo89/fXgtHu/ueZfT28Uc7LRXmUpm09+hw/YO6LC9g1E2CAD8dvc33n0KI0SKE0uxNpao6FrRpvHa71zvKr2LdF4A8HL0snrs2ZizvNslQgnGNzL9HbcXXUK6GG0rKTFSv3xtq8d6qfhjnyp7VMZkx8pwUpu+ye9RuYfuMTtGrZJCCRHLOCDWaOB2zfpaQ1rG1B8Dbydvm/crTkiMEG8M35z5BmdjzmLZtWW8gXTW8iD1Abrv6o6P93+s2+YocsTs87NxIe4Cxh0bx4m7YAdY7ni4AxmyDPzv+P94W4WzGX98PG9ApdYlw3ZZsGNGVt9cjVxFLqefRXHAFztR2Lbzd1LuWOWj1pKUl4SkvCSLn9mrhFQktXmfEPcQ3eOKbraJEYCxxvAttrZiS9zBzMiZvNsruVeyqlNyabHg7QU4MuAI73sz19W4sHTJzsEyofV/Q1c1v7vrv77/IcDVH05m3GGqaP3/hftlfXaXj0qFUIX+2qAUCOCSZlspjHYV2+GzBp9ZHljCkBgh3jj+uv8X2m1vh+lnp+u2XUm4gnOx5xCTHYO9T/eazanXmvHZqYP5qnyTgWl8xzIsCGWKW0nGC/aeJ3vQ779+nMXcsDT68RfHOTEahliTjVCWsDWW4vA7h9E9tLvZMbYuxMNqD8P0lvrvpL+Lv9EYS5YGZ4kz/Jz9zI7xcvSyaD2p413H7Ot8eDt5o4V/C93zhj4NOa9bW6yrJBjbYCw6VeoEPxc/m/8uPzvX5DzniznhY35SCjzz0rG843Ks7rTa4ngXM5YPyHNMWkaqyuVokKDPYHNL0btbK6hU+CaFm1nj+TgCH1UfaHE+WpxUJd+d2RpeHVlLEMXMrse74CJxQZvANhh9dDTntVxFLu6k3IFGo8GsVrN0BZhS81Ox6xF/bIgpitJB1DCYFAAOPDPOMjDMBrCU+aDNNiEYHEWOVtfPkAgl8Hf1x4i6I8wWhDMlcKY2m4r5F+cbba/gXIETwMuu0AoAzfyaYWTdkbiScMWk8K3mWQ0+Lj66550qdcLdlLtQqpW6+BVrXBL1veujknsl3sBsUwwMG4hK7pV01qt3q78LAGhQoQGuJ13H4NqDjXrUlBaj64+2PKiAGjI51scnwLXPGiSm3IPfqYX4KlQfFFrbSteLGABUCrxV0bgqaz3vekZuUmcTlhGoFIAsG44mYjEXJCYjSKGERAM0y8vHEwf9966CUoUwtQKzm0/D9Av6QnqTU9NgrbPG+cFBoKMSENlXDpBlhHij2Xxvs5EQAYDDzw5j56Od2PV4Fw5EHUC3f7ph7vm56LGzh81pgNmKbNxKusWpOmktpjJTXgdsiTuwN+zqpdZSvVx1HBlwxOTrnSrpe7PU866ne1zJvZLRWDcHNzT1awqpWO/acRQ74reu+ngYbTo2O/D5+sfXcXPwTezrtw/vVHsHXzT6guMeGlB9AA70P2A0T74MmOF1hnPOXdOrptEYc1TzrMaxfmhjZlZ3Wo3N3TfjgxqmS/wXFxJ2fEQh3JSjag/F37HxcFdrIFTmwk/OxB39Eat347hLuXVZxBoNhlZ7z+hYAgBQK4GoU8BGrhXtnervYFOXjZw4kfez+Ive4dQvgDwbTgZipHlePq5GRaOyQgkJgPeyshGiVELBqlzrWSBw+vo2x+ykFP37eHkZzf2aAQCkBiLI0fC5RgPMKQ8kFa0+SlEhMULYjeS8ZLP9JG4k3bA6eNJW6wQ7uHLy6cl4mf0S2x5s4+0rYYl8VT5GHB5hsjvom4qz2NneU7Aac31QzOHnwu8SMYxN8JDqMxoMxchvXX/DmffPoIZXDY6QkIqkaOTbSPdca9FgF7QSCUUQCAQIdg/GzFYzdcfe0n0Lfm33K1oFtIJAIDAqrc7XELBn5Z6cc9tS3KqCUwW0D24PhUZvXdK+Z2eJM+pXqM9bXI0tgFZ0XIFV4aswo6W+uFhTv6acOBpLuKv0C6mno6dV+3RmiUZnDetzyksDHJn34MFaoNkBoo5qNQ6/iMEkExldUKuA33oBz89iQKY+FV98bhkav7iBf2L0VYkryxVom8uTiXbqZ0CWDScDkeCvZESIIQ3zmTgzL5VKt4ALFtdDv+wcNJAVXAfTo7G0xSxsi4nD5FSuG8fdSIwUPP+P2z27tCExQtiFXEUu2m9vj7bb2ppMFf9o/0cYGzHWbAqrFmtLKGspzpgKuUpudSv2VwltvxRDNnbZaLJWARv2YjatxTSbzj2mvvkLH3txtwVXiSv6VOljtL2qZ1Wz+1X2qGzytRUdV0AsFGNS40kIdA3EwLCBRiKF3YqenbIrForR0KehTgyxxxl+/lqLnDV9iOpWqIvwSuEmX2f/TzmLnVHBqQJn0c9X5XPmYolJTSZBKBAiT6H/nhvOXyqSoqFPQ53FJNQjFOHB+jmWcyyH1oGtMaD6AN02AQRmK+x+1/w7znP2QmqyxEQWN916XlwcelTugapuwWgXz0pvz4wFCqwgDqxjsUXVZ+kZqKBSA0oZvmj4BbrJgQGZWfifdoFnuf6msBZ9QdI9YN9EeKvUGJ+ajnc0LqimUKA/yzriqFbjp8RkQKMCZJlGlhGFid49vioVjkTHYN8L45ouOvJS4RR3E7XkCvTLysEw1zDdS2zhFaRQ4P3MgjllWL7OliQUM0LYhdhs/T+SUq00avXOtnTEZseivGN5XedTgAkaTclPgY8z4z+31OzNEEtNpmyhuKtFFhV/F3+L769BhQZY3Wk1mm9pztnu5uCGJn5N0MSvCRRqBTbfM+15ZltGOgR34DR/4+PvXn9jyIEh8HL0sig2PKWeNjUHbOHfAsPqDENDn4ZQqBX478l/AJjAxricOIypPwbXk66bdKUNrT0U088xwaWGVpS2Fdvi4qCLkIgkGFJ7iM4Kwf6OqqG/wEuEEng5eiE1PxVbum/hWC3Yx9bGnISVC8ODtAdo7s/8LTpV6oRtD7ahrnddq9+/IeyF+vh7xyESijj/Y1U8qtjUn8jX2ddo/oKok0BAI8CRWbwFAgE2dd0EjUaDdFk6XCQunJYGfAXvEnMTzRZVq+xZGdNbTsfsyNkAgHoyGaIKYiY41h+NBrizEzi3DIi9ChTEgNTNl8Exaj9++CADWFADyGLF4ry4ABT8DdjBpa4s14pIu1mZj1H1RgE7Db4/j4/qHjqY0EYjMzIBDWNt6Zibh99j41FZoYCLWqNfgNOfw9GRm53VMcdEgLpTOfjlFQifBh8B11n/o2InwCMQSHkMbGXcZmIA4x1DcCX5JrxUKsgFAjwq8LbteRkHnSTNTWYsPXaqNUKWEcIuCIX6r55hvYh9T/fho/0f6Z4vu7YMzf5sxil7/uXJL9Hx7464knAFibmJut4epYnW585u/20L4xqMK8bZ6DGVMnqg/wGsDl+N5v7NMb/tfDhLjN0sbAuTYYClIew4DEuVVQGghlcNnBx4Erv67OIISz7YYuXqx1c5d9gAUN6xvO6xn4sf1nZei1YBreAkduLc2VbzrIZZrWbB18UXjX0b855rRJ0RnOwTvvof2oWcLSzYi7thsbbdfXdjR68dqFmeG5fh7+KP1gGt0TG4o86ysCJ8BT6r/xnmtGLE3P8a/w8zWs7Aso7LeOdrCu37C3QN5CzUzhJnnXso4t0I/NP7H/i7+nNEAPv9831OWjHSNbQrWvq3xETvFsDvfYA/3+WMEwqEEAlFKO/E3Dw4SfTWE/bfXBsk2sElGBqeVgc6Yq6hvX8b3dP6MhmWJCTh79APuJaRm9uBHcMZIWKKLAOBHncDOL8cABN7MbtSb3zf5nu4nlqgG6JblpXGKfiGmG7nCCAzRjemoUwOD7YQKUDIejvL4xMRzufSAQBPlhuwQpjx601GGG0SybKwOU+KpYnJ+CYlDZUUCsxITmHen/Y6oJIDGbalBRcnJEYIu7P9wXZMPjVZ5+qYcnoKpyPp1cSr0ECD+Rf0GQpHo5k7kj/u/lGkmiJFoagBnJYW5MJiqphWRbeKaBXYCus6r7OqxoUpN44WdgqlVCTF4vaLEexmvlS1o9gRjmJHi0KniW8T3WOJUIJ2Qe04r7cPbq97zNfV98smX6JdUDtOpgP7/bALPE1oPIFTebK2t3XZFE18m+Cdau/g66ZfG1Wb9ZB6IMzLeKEQCARY1WkVFrVfpBM2Ps4+GNNgDCo4VwDAiMAB1QfY/P366a2fMLjWYKzptIY3ZkR7rurlqgPg1seZ12ae7jFfamwFoRQ4vwrSnFSs6bwGw54XdEN+Yb4uDFukOihlwIkfgA1dsfLtX/F9lfcxOvJPqLK47gZXid79pzryHaTn9X1tBADa5+ahxrEfoWFbJHd9wnt+3Tcj3nLNm35ZOehVpReECXd024RawZMVD+yyvhaHg7k0XhOIWH+zVnn5psWNB+t/18ug2azEEfCtZbzPza0QKJjPq5JSib0v4zAgq0BAh7QBvAu+q6mm+2yVNCRGiCKz7+k+dNjeATeSblgeXAC7aumiq4uwP2o/FlxegA23N5jc50X2C3x35jtO2XGhQGi23kZJUt6pvOVBZnAQOWB1+Gqz9RlC3EPQu0pvmwpsaRcbaxhWh4kNGVRjEFwlrpwaC8l5yWb3ZWcziIVidAjugD399pjZQ0+7oHZo7tccQW5BOlcbmzaBbTC71Wxs7clUmzV0nbDjHfjEyJDaQ7C0w1KO9YK9MNYqb3zB/qrJV6jhVQMTG0+06j0IBALMbDUTH9f62OTiX5r4OPvgq6ZfIdg92HI/mdhrGBzwNgCgW2g3zktCnmXB8ch04OBk4M+CeA9r4k3Or4LTLn1skHRpY+DEfCA6EuUeHESvnFw4aYw/OXbKtAiA49klvIfXWGGt0LGqjeUx6dFAfgaQo68RpHuX2z4EbmyxeIhR6RlompePDqasGqao2BSuDfRFFjlyUOoBsL//zqzrjqtBgLXYEfA0cUOQY6L2kcQZ6LkQGHUMCGrBP6YUoJgRoshoa16MixiH0+8zjccOPzsMT6knmvk3492Hr+YDXwVQNhmyDPz35D9dPADALEpsE7nWV1/cBLoGGgXSWnPneuzdY3AUO6LVX62MXlOoFGgV2Ap/dP8DA/caFyna03cPAl0DIRFJ8HXTr9FuezuOiDNFywB9AzYfZx+zvUXGNxyPAdUGIMgtCF81/YpzV2wY9Nmjcg9O7xr2WO1dPls0+Ln44Y9uf2DyqcloHdiacyypSIp1XdZBo9FAIBDgbspdeDt5I/zvcGigQahHKJr6NdWNNxQjbAFimEliCpFQhN+7/Q6lWslpIKhlcO3BGFx7sFXHMmRWq1kYf2w8JjSeUKj9rUKtBvZNBPzqAE25nZehlAFiKwVr9AVgQ2dUcwvA2c8vMJYIlqtErpZjR68dyFXm4vCzw4xw+6tApCYUWETYcQV5acBvvQHf2kCf5cxr8lzg4GQ4A5jTZCBU9/fCg20tkGUxabEAVAZiUigQYmjtoXhyaSUa5cs40ogtXNTFLQBTHgGLGwB5qboFXWjpHK0nAGcX6Z5+kWZ9nBMH7+qo6uyPEekZqKCNWanYDIi5DHSew6QP3y7olcQWG26+RsfhuHH4aPgxcI3VdkHkwFhH7AxZRohiI12WjvT8dHxz+htMOjkJIw6P4Ph1z8edx6QTk7Dk6hIsucp/t2Mrd1PuYmzEWABMmqAt/UIWt19s1bgaXjUwpZlxkTFLYsTX2RcVnCvAzcENA8OMxYbWomPK6hHiEaK7s/eQeqBTcCfO677Ovtjfzzhwl50ZUq1cNbNzFAlFCHYPhkAgMDLP96rSi5PNML3FdOzuq++Ga6nSZZ8qfeDn4offuv2GT+qZMKMXCIla5WvBx9kHJwaewP5++436ZBhZRoQinXWD3bfDEg19GnJETnFRx7sOIt6LQK8qvZiFPb0EOpc/PQZc2Qjsm8Q8V6uALe8DMz2A7wOBxPu6oZx4CrUK2PkJEFng7riyifmdFQt3oSMTq7CqLYbIGYExodEEhHmFoaFPQ0xuNpl5T2zB9/cwIIdlNXt5GYi/Cdz4C3hUUO/khb53U9/MTLyTzY2pwZFpwH1G2DbL58aMiYQiTKrQEisSkiACNxZDw3rmbUYneBYs6G3ybLBQpEczQoSF2JLeCWxkYYAVVO0EhM8EJE6YkJaBD7XZLZVaAVNjgMZDOFk7cPLUP3YxsCr2XsKIwVHHTZ+vVh+AndZtGEtjJ0iMEMXKnPNzsOep/q6TbbUYdXgUDj8/jLW31uJc7LliOV90lv6i7yJ24cQifFjTfPdPSwu1FgeRg86fz8aSGGH3nfmuxXdGQZjmxMikxpOMtk1swnUfbOy6EUHuQZxtu3rvgkAgwC9v/4Lvmn+Hb5t/C4C/eZglHEQOGFhjII4OOIpD7xyCs8RZF8gIgLevTlHxcvQyek8A8HbFtznuHAEEWNNpDX5t9ytGezUBLqxhMiqshC+eo8go8oCHh4E/+gGL6gJRp82Pz4wFnhy3ft556frHGg0QcxV4WFCtV61gXCDyXODJcYyoxVh4elXuxQiEm9uAQ1OBu7sBdhq6LItZgJPu4cuYKFzw64UGu74Acg2tiyxJcGcnkKnPkkHKY/3jhILYjHyWhcBU9+qCYMlvU9IwOl0fOC0SiIDj35v5IBgWZChQL1+G1fHGlr+/Y+IxJykFI9ML1zQzRM4s/hbFTKA+tgkVbCsip+OjHYCrDyAxiNGq0QNwKAgubTcVEEmBluMAD9b/h8QR8C0o7R/SFigXwjwOaAi8PRnox1OmPrgFMIUVqJppJkW4FCE3DWEzu5/sxsbbG7Go/SKjAk+Hnx/mPE/NT7WpuFJREAqEHDfGlGZTcC/lnq51fYh7CCfzJcgtCGs7r4VYIMawQ6braihUCs4irMWSGDGsZTK/7Xx8kPQBpp6ZisTcRLQPYoIwDQNZN3ffjPoV6hsdz8/FD0NqDdF1seULAtVaFNji48KgCxaDUc3BrpvBzsDh+0zYFLZWCB/OEmcceucQGv7B9EPxc/GDh9SDqbUxs+A8HhWBGub7yWh5L+w95CnzOC4tAEDKE+YOuUp7/h3Nse9Lbprl5Q1AaFvT43+tw9SY+GgnULWj5eOzRYsy3+guHtAAu8cBt/9BHbEjzn24Da4hbwO3duiHbP+Yu4ssg3OX7BzJZJfg2BxmQavZm7kTN+cKO8iyGsZe189PN1fzotVDrcbYtDRsd3NGqkiEVj6NgLijvGN9lfr/72qZSfgznWUxqNUH6DQbWFwffioV+hpaYwBmsR70N7DcvHVsZ0wccoVCTk0OI/qvZdJoP9gGCMWM+2xBEUQuO7ut3xogiOXi9qkJTHnOCBa1Gmg+GvArSP0etA24+jvXdScQAO2/YR7f3A48YbWHkLgAQiHQdyWwZzzQRR+8bE/IMlLGUagU+O3Ob3iYZroU8OmXpzndW7898y0epz/GsmtM6mE5qelW9in5KUjKTcKzjGeFmp8txbRic2KNYlHY6ad85vwW/i3QxK+JUXwEe6HPlGfyCg92pUZrcBQ7opl/M/zb51/s6LVD12iMPceJjSfyChEtTzP00e7az10b5Gl4LC3OEmer4yqs4ciAI9jZeyc+rf8pnMROnMqeABM/0SGog653SXEhFoqxsN1C9KnSB+/XeN94QOoT421a1CrO3b5EKMHIuiON+5AsbQT80Ve/qNoCW4gAgNTE90NWYAXQZrNEndLP0Rzs4mCyLK6rBGDEyu1/mMfKfLj91of5u5v72+dn6INS2VzeAOz+HNipDWi28vvzYD8j6NjWEAsZN1q2xMbjy5Q0fHV+KxO/wWJpfBJGp2XgrTyWyDGMOxM7Au4VuYu6IW4BgLtxg0IOIW0hAbc4GMrzWFHrFZSID+sKVAsHHFg3B65+TA2Tyu24+3gYWP3qsD57tmXEj6eRofZ1oRDo9iPQsKD8gUdFRni4GgeCAwA+/Jtx9/RdCbz3O7M/ADQYBHwTC4R149+vlCHLSBnnr/t/4ZfLvwAAbg0xTn/75vQ3OrfLrSG3OL7og88Oopl/MziJnTglrNncS7mHwQcsBwXyBYgClmtdsEnNS0XdCnXxOP0x7+vm2qbPaDkDnx75FBMaT0C7iu3g5uCGln8xd80x2TG85cTZKYhs3BzckCXP4s3Y0L7OdhOwszwsZUF8VPMjnI09i7ENxuoERu3ytbE6fDXUUPPWDilu/Fz8dBVIz75/1ih2pH+1/uhfrX+JnLtTpU6cnjAczPWf+b0P8Ow0MPYSUMGKbKOYK0BAA/1zWRbjUqkarjedW8LRnREI2QmAW0HWw/UtwL+fAd1/0Y8TS4FL64AjMxgrSXBz/uOx04dlWUychiWy4pn6Eaa4vZOpt2GKR4eZ92BtuwWNGvhvHBBtuxs2UKnCEFZJdTbt8vLQzpLLRJ7DNHub9AD4wdjVB4D5O1iy1Nb/gPmusPlwO7CkIf94LWzrY+vxQNMRwLmlwNMT+u2fnAAgYL5DUae5gaPs/93iTPsXigCpKyM+DDEoNmlPSIyUIXIUOXAUOXJqKtxNvWtyfHRmNCf+AzDuHjs7crbZ3hJ83Uv5qOReiVeMmOopMq/NPHx75lvOtm9afKO70x1Ug/nHY2dddAzuiA9qfICdj3bix7d+5OzbwKcBzn1wjvPZBLgEIDYnVic6lnZYis+Pfa57ne1+6hbSDR/V+gg+zj5wkbhgx8MdRimTpmCnMlpKEW0V2AqRH0QaiY5WgcbZOqWBYeXcUod992pqLnE39YvLjb+A8Bn84zjHNcha2v05cGcX0Ggw0Hup8RyiThgfw8ENOPkjE8vRZzlzJ/tvQa2K/axKnmnPmHEAsKEz0PVHoAVPF9p8VvxDXjrzXjjwfHcsuQ1YgaYmSXoAWBMf5OoHZMcXSogUC1qLkymLFMCIET5LkXugrjAZXA3cj+2mAl6VGatL5kugdj9urIgWdtdbsQMjMtOe6bcFNAScvPSWieqdufuzLSOG8SNlAHLTlBGS85LRYksLDDnIbfhkrvOlobVj3a11SMs3toAUpiOqIXyCplb5WrzuhdmtZqN3ld7oENRBt+33br+jY3BH+Ln4YVH7RbqUYsNS3N80/waXP7qMjsHGPnqRQRnkVZ1WoYV/CyzpwGT+tAtqh+09t+tedxI7oVtoN3g7eeO7lt+hXoV68HPxg5uDG4bVGWayyZoh7Dma7LfBojSsH68NbGsB3/cwNQpYzYrb4BO3ajVzV/2bvgopDKuC3tnF/L76u/H+93YzQatGxy0IKgX0GTB83DRIaT84We9uYSNjWQ2SH3KDRAuLNWJkhQlLjSGGBbhKG+3nY3jN8G+gf6y1UI06BlRjiYE6LEueIyvWqVpnJhAUAMZeACY9BN7dBLSyUD1ZG5TOdt2MPKYXIrz7sMR0CRVEfJUhy0gZIeI5E8BkWJiMLz0zMjYSF+IucKpXAsDiq4t5G47xxZsIIIBIKLKqLgYADKo5CFvu64sKfVrvUwyvMxxnYs4YjdVmn8xuPRvRB6ORmp9qstDXhEYTcD7uPIbUNtF10wyhHqFY23ktZ1uYVxia+zeHAAK4O7jjx7Y/QqVRWUxztRaLxaoIBo2GWXQ4lU957ngNK28aihG1GlgfzrhlONvNlCjX8uIicOZX49gNLbksKyK7UJU17BjOZElUCGOyHQ5O5Wat/MtjObEhm6jYqRrOxB5ER9pvDr4mKudWCAPirjOPtUGfgY2ZWIrcVCDpPiMazhVYvBxZ3YcrtdaLG6kr82MNgQUl9dtOArITmfRcc0IEAOf7WwYtIyRGygh8RcYArotAoVbgafpTfHKEqQmRITe+82K7Kcxx5aMrmHthLnY+2mnV+CC3IHzf5nt8c4aJAK9ZviacJc684kdaUNzJQ+qBHb12QKlRmqzVUbN8TVwYdKHYSq8LBUKs67yOs82cdclWXoVKnq88Oz9hhMBnZwEZS4zwuRIML+qGYiQ32ViIAIDKgoi++geTuWKOy6xqwpkxwD3rqtPq94llFtLdn3MasplEo2FET26K5bHtpuqtNkWh5yKg7gDGNWIplbkkaTEGeOsr/tfYIkUrErQ4ezH1PNhl0KXuTKBrVixQs5dt8/j8KlO3Q1uS3dUHeHejdfuyLTpkGSHeVExZKNh39NPPTsfep3t1zx+n8QeCWmJM/TGQiCRwk1ifbSIUCHlLd1f2rIyV4SshFoox6jAT2c8pFy0UQQSue8WQkuoBUxJY46Z5Y0i8z9zht5sKVLeyDooiX+/WeHpCb3YHGFHRZDh3vGEciZFlxEQGiznLiFplWYjwse0jy2PYKGXApfXWCREAeLCvIFvDhBgRO+pTbv3qAj61gETTMWMWCWgENGGlxLMtCnwIhEyAa1Fw9WUCgg3pakZYtRjDuPCk7lwXDBt2UKvUDRhzjrGalDcd9M5L+Sq276PFp0DAOHmZz4B6Q6GYkTKCKcsIW4ywhQgAJOUlFepcnzVggvRsrS/CFhlsS0ebwDacxmkKc10+X1O0ab62VBPloFIyWRHm6iIUNw8OMLES5oomaTTAi0tMESulQUbGjuFA7DVgy3vG+xz+DrjIdZEh4yUwjxVcKHHiWkaubQa2fcy0ik8oWGQNvyuGYoRdD4ONOfdiaRWJerCPKf9uSLNPTe+j7brqzRO42nmu/rGDi3GgpiUaD2XqjmgxdItILYiRHgv0bhItPrWB4Jb84/moXRDb4eZvXX+cCjUYQdriM6ChmSKIrj5Am4nA21MYV4xTucKLisIidQWmRAMTiyAQX2NIjJQR2JYR9t23uVgHvuwWNnxBoGysrcOxpD0TIMoWI4bWDPY881UmFpDXmA1dNuD0wNMIdjff9dYk+yYCq9/SZ2WUBn+9Dzw5Bhydxf+6Ig9Y0ZKJyTj5IxBpkIViyp0Qe43x37MzTgDg/Eruc5XSOIjz3m7GTL73f8xzQ7FheMNpSoxoC3Vd22xs0Ui8Zzy+JOALlgWA8izXpYeJ74uExxpYkZUB4uJjffyDlrZfMi4ZLYbCwpTVQUu5EGD0GWbR1yKScANMLeFVGZh4Dxh32bpePEIbsr3CZwDtp1o/viRw9CiT8SIAiZEyA9sywm4dXljcJG745e1fzKb1mqrDwWZg2EBdO3hTlhEtTXybwEnshDaB9m/qVNyIhWJ4OnoW/gBXmaqsOPlDsczHJmQmSm4/OgwksRbumKvc102kbXMEhtaN8vKKcWyHPJuJ+eBDW/L8yHTudm1JdZWSsXCYEiPybODgN8B/Y41jPbYUUzG3EDPVWc3BvmOv2hEYfghoYCCY+CruulcEhu5nil/51rJcb4NNizGAZxA3lkFbhlyLJcuINguMnVqtUlhfwwRg3BfuAYyQalzgIjL3OYooEuF1gf5SbzjZ8mz88+gfTg8XhVqhszQU2uUhYBZQc2m97g7GF6d3qr2DLHmWrmw8W4BYEiPru6yHTCUrUmlzogTIjAXu7zcuxZ5skGUly2IWn5eXmDtzU35x9vaTPwHNPwXWdTAeJ88xnckCMC4kdmAiAEQuY0z8UScZsVShBv++2mZyJYklS4Ip3AP0j529mF4jQgm3AqyhZUQgZIJbQ1oDKOigbEsGmEtB40K2cNAGaWoRiYFei5lCalEnjY/Bd8evkpsP1gxuyVQ61Vq62HSczpRMr/y28WutPmesa53mmD428UpBYuQNZ+GVhfj74d+cbQq1AhdfXMSiq4tsqnDKRlVwx8quHmoI2+XQKqAV3qv+HjpW6oi7KXd1YoTdgI4dwMonRoQCIQmR0iAvDXh6kknVFDkwKaVelblt49mxKXHXga0fAJ+eAvzq6cVE2nPucaNOAnNY3Xj57qQ1Gm7NjpM/6ItRGWJOjJirKnqYVSwv6b7pcZao3I5bXdNW5Dy9UyxRrTPXouFU0IqhYmNg/A1gcUErAfb/9VdPmb+dxdRSFr51mIDKWwV1dbTnZKcoa8/NpvFQpviZVoy4+AA5BY3s+OrjqORA6y8YC5c2MJkdaNtxBlCppV6MsF1UEkegdl/++XeaA7z1teWgWuKVgcTIG8rzzOdwd3Dn7Y4rV8kx7lghsgFYaGNQpCy/bbeQbuhbra/uebCbXox0DemKjpWYGBO2a6eZn74ZFLta6uuUAfNGceU3YM8XzOOW45hCVvsmMYtMr8X6cXk85f9Xv8Us0IP/Y57np5s/F597Jz/dOOPi2mbjcQDjSskpXJB1kfGtC9TqWzQxwlcxtkZPoFonJrDz1M/Ao0PM9joDmJiP+h+AU2mVvcCXCykoNw6m/okWF1M1TkxkbvnXZ4TlszPGYiS4JfM9MHTRsPFm9XEZfVpfBZbvf1olZzKi+q/RixGpu16MaC0xQ/czmT+GvV5MIRCQEHnNIDHyBhKbHYueu3rCSeyEQNdAo9cTcnhS46ygfVB7HH9xHABTEAzgVl/9qulXRpYOsVAMpVqJ2t76yHtniTNmtJyBDFkGp1EZu+CXqbohZYr0F8A/I5gAv24/lny6n1qtFyIAcHGNfhG6sompvdCuoBqlqViNpycYV4xIwm15by281gITi+bzc9b1ZykJPtjCuJv4GH0GWMUT11S9K9DhO/1rbSYyn9HLi8zz4Ye5fWk+3K7vSOzgwmSEANwaKIaCJqCgf4o1KbSmssi1sTzurGtHpYKMF4GAEabmKF+FeS/u/tyquEKe7Be+jr7sfbQuqZDWBS4m4k2FAljfIB6nPcbR50dxPo7pkpmnzOMtHW4pS8YUAgiwtcdWhAeHY0G7BQAAB6H+wiHhiVw//M5hbOm+xahC6oDqAzCi7ghOKfQ3Uoxc/QNY3wXIsaIQlSH39jDlui+uNu2qSLjD7VliLeeWMQvdJVYBN0NLhkrObVN/4nt9QKm5c2o7tvJZTyzBTtW1xJOIkrWMVDKz+EndTcc6VKipf1wuRP+43RQDS0YlYMRhveuDr1OrFk9W1gw7KNNUtohV8Sgm1QjzyysUeH8L8Olpxk1nC8HNmTk7ejIdb8uFclOJGxSk2fIVKgtsxATlvvsb18pCvNGQZeQNIS47Dv12M772dhXb6bbfTDK+c4zNLlydBIFAgNretfFre70JWMTK9edLE67gXIFjLTGHh1R/AS3Olvd2RVsc6+SPQPefbNuX3YtEwdOx9HkksLEr149uiUdHGGuHNm5i3yRGKIV14/bRMEVOEhP4ePg702N+qc4EHSbctn5emXHMnbTcBjFSkvReCry8DDw/y/+61M10ailbLAS31DdLc6nALbImdmQsDV9cBzQq/s//wx3A/b1Ay7H85zJVAr3DNCYFWZtxwocpMcXOcqpRyLo3WoRCYMx5ABquZaTXYiZDhz3/0WeB638yKcQmXUvEmwqJkTeEPv/10T2+EG+++dXL7JdG21oHtIZQIMTpGNMlnQU8vT/YzeWK2p+limcVfN30a1Rwsk68lCjZScwiEtS0eI7HFhamOLeUWUB6L2Mu4uyYCmU+cP0vZmHqv4ZZuO7tZl5j9ywxR2oU8OcA4+0nvmd+RhyxfIz9XzEugBfnTY9R5puukWGKP98taO/+ijQBbDSY6fbLhl1BVCjiuhO6/gAcnAI0Y1opoO2XzN+qzgB9d11nb271UK2YMRfbUK0T82PIp6eYInD+9fj3c/NjmsGZ4+2vGbda6hPudlMp14WFL71WJDG2BPnVMV9JlXijITHyhpCnzON9zAdfzEj3yt3hKfU0L0Z4rBXsYmrF0Szu41ofF/kYxcKyxky9ixFHi0eQ8PnLtcRcZRau04zrC42GMGZutoBRyvXN0S5vZLqGmqoT8c8oZqFrMozbi4OvBwtnvxGW34dWABU3CbeYn8Iy5gLjZtpgoqy8kxfX5WQNNXsCl1hVYFuP5waGsqu0aquTamMcOk5jfrIT9WMkjky59opNmTTXonRf9q/P/BQFNz/gi6tA8mPg2Gxm24ODtlvwCKIYsHn1OHXqFH7++WdcuXIFcXFx2LVrF/r27Wty/M6dO7Fy5Upcv34dMpkMtWvXxsyZM9Gli5W9KAiLZMptixlIl6UbbVOqlWZrhgD8lhE2xdW51u5oNPrCW8/PFF6MsBd/QzGilAPigs97bXvua9rPkS1G2O6LG38xYsRUBU1tBsS1P5i78fZTmfdkqYFaerT5119VRFLApwbzHt/6igmgPbuIO0YoZqwJq9/iPQSHWn2Z35XbMbELUjfGCuJZibGWaWNJ2DV6xI6Ah3GwOFx9mJgLrfVDKNRboF4VV6R3VeC9AksW+3tJEKWIzfa4nJwc1K9fH8uXL7dq/KlTp9CpUyfs378fV65cQfv27dGrVy9cu3bN5smWVTJkGbiTfAe5ilxkybnm/lxFLjps5ykIZe54PN14X2S94MR/7O+/X/dYW/Z9VL1RRvuNrDsS9bzrYUOXDUavvbawa1c4e5seZ4m1rL/LyyvA0ibAgclMLYi5FUyXUdeuUWwx8jurJ0jCbSD2unVzyE1m4kL2f1k8XVpN4eZv/dgx55kU1uJCW5BLIGCyVTrN0sdD1ClwS/X8lbEkWKpTI5QwLhctwS2YuAbvaswi/e4moFnB/wE7vdWcsPCvxw1kFQheHSFiCAkRwk7YfCvbrVs3dOvWzerxixYt4jz//vvv8d9//2HPnj1o2LChrad/o1GoFHia8RTVy1XnuET67+6PxFzG3CsUCHF+0Hld8a+HaQ8h42udboaojCgAwPhG43Em5gyuJFxB15CuiM+J140JcAnAqvBVyFflo0NQB5OZOXW86+DPHn/a/F5LjegLTFaAq4/1+7CrdrIrTirymQC7ap2YTAG1Grj1N1MF0ivU/DG1LoiUR/ptZxZyS2NribsB3N9nOoMGYOJEzi6x/F5Ki36rgb+HWJdB41OT+Qzv7zU9pno35j16BjNZM+bov9Z424TbTHyGXx2g50J9dsl7v+vLuXeaA8ReBeS5+noelVoygbTW4BHIuIecPK0bTxCESUrdrq5Wq5GVlQUvLy+TY2QyGWQy/QKbmVmI1MXXkMmnJ+PI8yOY2XIm3qn+jm67VogATPprVEYUMuWZiMqIQjXPwqe+eUg9sLbTWqTkp8DPxY8T/yESitA6UJ/ayCdEXmk0GiYTYlMP5m74u3jL+wBA/C1gOytuZf9XTFZF/YHAk+OM+d+pHDD5GXB0BnBuCRDcChh+oPjmzlf62pDoSNO1PkqChh8zbh9TSN2YRd0S2uZqlvqY+NQEBm1lMn1+5kkrrdSaSYl9Zz3/3bxrBeYH4Ka5soMmW4zRB1cemwucWQR0nGn5PXDmaaKcPEEQNlHqYuSXX35BdnY23nvvPZNj5s+fj1mzTJiw32COPGd8yRtub8DbQW9jy70tHFGiZc3NNYiIZu4WR9SxIujQBC5iF0hEEvi5+AEAanvXxvSW0zmVU19LnhwHdo5ighYBfdM0S6hVxsWqNCrgxhbmR4v27v9cgWUimlXlNvo88OIiU73UGviKPlkDuz5ISVGjp956UaOnsRip1Qe4W1BtVeoGWLLQvfubvqkZu6w4H9r6EoYlx33rAMP2F62vy4gjTPAoO8ujw3dMBgxft1uCIEqcUhUjW7ZswaxZs/Dff//Bx8e02Xzq1KmYOFHfZjozMxNBQUGlMcVXArlajm9Of4PIuEidQGGjFSIAsP72+kKfh8/a8W71YupIag9yU4GUJ0z6qlppe0GsTBvqrzw24TrQZnOYy54p7DmLgzoDgNs7rBvrwoqX4RMP7CJWUjfj10UOTIqsVjix+4g4m7aMMscuuD4IhUDnuUwdksZDGRFSWCGiJagZ/3YSIgRhN0pNjGzduhUjR47E33//jfDwcLNjpVIppNI3pAJnIVCoFIiMiwQAPMt8VmLncRa/Zq4XS6ztAKRFFX5/W9we7Hod2sBfDaui5S0rF/wrG60/p7XU6gvc/dd4e+V2QN8VejFiSZiwBQhfx1X2+3VwZWI3jswAsgoEVpv/mU4/5hM3n5wArm9haq2EsLJeWn1ueo4EQbwRlEo5+L/++gvDhg3DX3/9hR49iljRrwyQkl+I0uEm+OXtXzjPP6r5ke5xYTv2vrKYEyLshZOPxxHAkenWn4vd+8PBlaknwa5BEXvVuuOcXWx5jK2YamL2znqm/ki/1UzMBTtrhE33X4A+K/QiCzDOlnEL4AbtOrgwVVcn3dNv02iYfiwA08mVjROPZaRcKND9Z2DoXsrqIIgyhs2WkezsbDx+rK/4GBUVhevXr8PLywvBwcGYOnUqYmJi8PvvTN76li1bMGTIECxevBjNmzdHfDwTSOjk5AQPjyKaWwkOdcrXQXmn8kjLT8OsVrPgLHFGgGsAMmQZmHN+Dqa3nM7JmHntglLNYUlsKGVMEzg3P6DTbMalE7mMCais3Q/Y3L/w5xY7AFsGWi9AbEEoAdQKy+PYmMru0Fb8rP8+8wMwzdrOLAR6LgJirwF1+us7o/47Rr8vuzx3nQGMheUSy0XIl6rqXB6oUJ1pbW+YIs3nEuFz9RAEUSawWYxcvnwZ7dvrizRpYzuGDBmCTZs2IS4uDtHR+uJJa9asgVKpxNixYzF2rL6/gnY8UXTEAjGWdFiCFv4tIOFpS/5e2HvoEtIFHlIP/HzpZ932ILdiisNRq4GMF0zjL3uRa6G6ZuxVfYvyrATg5lb9a38PLdq5lbKSESIAUKWDPu3UEN+6QL13jS06FZsC/dcBuz5l+qFkFwhQvuaDHaYxlVo9gwEY9DHxMPH98KrMCBttm3dDei9j5tx4CPOcXWODTbkQpohY01FAhTDr42wIgnjjsFmMtGvXDhozd6GGAuPEiRO2noKwkWuDLReQ0zahG1RzEM7EnMHQ2kOLr2LqwSlMZ9leS/QLkDlirzMuldr9zI+78y9TK6L5p5aPmWUhEPTMIv1jthApDkwtypZo8z9mMb6zi//1UceAY/P0zwObADGX9c+7zGWsGGwxUr0bENCA+anVB4iYxViAAON28wATIOppInuq1Tim8mudAqvRx/8y2TNtJjDPTbmDGn3M/Fhi7EWmSy81RSOIMs8bUr+77PFOtXeQnJeM98JMp0jzEegaiP/6/le8k7m4mvl9eJplMaLRAGveZh57VzfddRRgimgBTOdToZipPWGqcqWliqSmrAtFwTsMSH7ALYzGh9SdaXrnVQUYEwnM1WaSCRjLhMhBb7Vh498QqBrOFP3yqQ0M2AAsrsc9LsC0Y79eUHiu7wr964ZxF7ZW/ZS6AV1YYqhKe+ZHS7VOTPyJtnaIrYilpjvfEgRRpiAx8opgztqkpX6F+riRdAMA0+F2ZquZJTwrG1FYKHql0XDdGTlJzDa+RVLBqg3yW0+mV0z3X5hCZi3HMfvc3we89TUTfxBtpotsSRHYiBEjlvg6inFBaNTM73ZTmf4yLT5jUljDZ/GLEaGQSWd1DwCqd2EyWlp9oa9vohUjvZcyn4tQDDh6co9RkmXHBQJ97AlBEEQRIDFSymg0Gqg0KlxLvIZ1t9bh2+bfQqVRIS4nzuK+w2oPw4QTEwAAnlLPkp1oYbAUaLl3AnBlk/75730Yq8ewA8aLZl66/rG2ad3+L5nfbLdGTjKzQBel42thcalg3ThtcS1tdkq7KcyPFr602XEF7hgHZ259DnYWj675mggYdwWAhhEwBEEQrxkkRkqZyacn41L8JSTnMTUtxkaMtbqWiBNr0XolxYgl2EJES3QkE5fwOILpRdJ2EiNM8tOtO+bV35gfe2CpiijABHNagk+MeJso85/2TP+YLYZE9K9MEMTrC91GlTIHog7ohAhgW1EzdpEym8WIWgX8Oxa4XAJFtvhIegCkv7Bu7MGpTHzIsTlA4l3g/n5gRQvbzymSAmHdbd+vsDha6K8CWBfIKbKhpkabiYCDGxMsbJUL5hXtDksQBMGCxMhrhJO4CJaRe7uB65sZV0lRUauYIl+myE0FljcDFtWxXP8D4PY8WdkK2PpB4ebl5GlbQGSnOdaNazcVmJlhvL2oZcm12BLXUbExMPWFdVlLAFBvIPPbv77t8yIIgiglSIyUIiq1yuqxIoFxzQX2Nk/DQEVL5NhQ6vx5JFOLwxT7JgK/VANmegDHv+e+9uIit25HtpnjFDc5yYCClWY7PQ2o1Mb0eI+KxtsafGS8TVsnY6RBPxqpB1ChJndbu2+smqpZqnUx/7ot4sWvDjDxPjDiaNHmRBAEUYKQGClh2AIkX2V9PQoHA9O9s9gZFZz1MQKuEhM9P0xhrRCKvgBs7AosaWjiOGpu7MfJH7mvr+8ERJ3UP095jFKj24/cjB6h0PzCHVqQYuxVGRh+GJj8nKmtoaXFWCbAtlZf5nnFJtwS6o4ewIjDgH8D/bZmo4r2HoJbMim8xYm7P5VXJwjilYbESAky89xMdPy7Iw4+O4jBBwbjRuINs+P/6vGX7rGbxA3tKrYDANTwqoFdfXbBQ+qBHb12YE/fPRDYmrKpVvJv12iAl5f1GSvPzzC/FTnM73t7gFleQMQc4NkZ4O/Btp1XK0ay4s2PM4dhXxM+ev4KNBnBTQkGjMWItoU9wBTb+uopMPoMENyccfP41AQ++gcYcx7o+j0w/CC3dDm7QJijO/NTIUy/TeLE7eliK42HAVIbhSZBEMRrDoXglyD/PPoHAPDVya8AANPPmW/EVsdbX9GynGM5/PjWj7iWeA3N/JrpyryHeYWZ2p0fbR0PU2LkwX5g6yCmANm4S9wGZkkPgW0FbovTvzA/tpLymEnT3VlIi0H3X5ig1F9rmR7T4EOgyXDmsZEYMdDb5asAz07rn/NV/6xqpqs0u0S6NmakSgemTojUAxA7Mm6d1Cemj8HH4N3A83NA3QGWxxIEQbxhkBgpRTLlmVaP9XL0grPEGa0DW1u3Q9JDpvBVo8H6Hh9HZwE3tjKt2TUsN41ara9Hcetv5nfyQ+Y3uz9I9Dmr52uSc0uBG9uAHBMBr/4NgKT7pkuqa90eDm6APIv72sT7THn04Fb6bSFtmJojDgVN1zpMB56eYB6LnRhhc2UTf9dYa/DkESP1BjLFy6TujPB7/09gzwSg/VTrj1v5beaHIAiiDEJipBTxcvRCTHYM72tbum8BwGTJpMvS0TW0q20HX95U/zisG+MqOLOQeR65VF+tE2CKkwkLsk7Y2S6KPODJMf3zFBvv7k1hSogATI+ar54Aq98yb01w8daLEQc3oPV4JhbCvRd3XIfvmO01C7ZXbAx8fhW4uIapZlqhBjB0H/O7MDiVAz7Yynxu2vogAgFjHdHiUxMYUQLl5wmCIN5QSIwUI3KVHKdfnkZT/6Zwkxi3QzclROp510PdCkx/j+09t+NG8g10qWQho8IUUSeN03fPLeVmlajkrBRYlhjZOYqJEdESXwpVTWv2ZmIkmo4EDpmxJLAtNj1/ZbrV8iF1ZYQKm/JVmOBWLSFmMmysIaxb0fYnCIIgOFAAazHy570/MeHEBHx25DMoTcVo8MDOnPF39UfXkK7cANWUJ8DNv/VWDI0GeHQEyOARN7mp/CfRBqYCgEoBJNxlftiWEbYQAYCnx61+D7xYY33oNJv53ewToKGZAmG9FusfU2YIweLSs1SsO/3Uqv5OxOtNtkyJPLn1JRKI1wcSI8XIsWjGxXEz+abZNN6KrhUxuqo+UNHXxdf8gZc2AnaOBA5OAeS5wMNDwJ8DgGVNjcey02pNIc8GVrZkfiw1tysMvnWAcqFAJZ54l24/c587F8RuiMRMF1g2rb7QP2bXVRFRp1dCz7urIjF33z0culOKNW2IUidfoUKdGYfQeO4RuwrPF6m52Hg2ikRRMUNummKkjncdXE+6DgCcku9sOgZ3xKL2i4BrfyI0MRnb3VwxqfEk7qCrvwN3/gUqNuVW2rywqqBeSME/ojb91lZykvSPM2MLdwxzjDrOxFGc4sm+qdKBqQYax5PmLGal0A47AFRiBaY6lWONI8sIYUx0qun/B5Vag6x8BTyd6bvzuvIilblxypWrIFepIRUXIYW+CHRfchpZ+Uq8TMvDtJ5msvwImyDLSDGiTb8FgKTcJN4x5RwLFlWNCt1zcrEpPpFTzAwAsPtz4EkEcPIHYLNBqueltcYFzJRy2yaam6Z/nHjXtn3N0XIcMHQ/IxZEEv5y6Y7ugNzEosEu9Ga4r5On/rHKehdYYbn0LBXLjj2CSv16mP6PP0hEh19O4MrzNMuD31AcRPyXs+MPEtH8+wg0mH0ET5KyzR7jaVI2Tj3k/9+1lpsv0/HLoQd051zMqFjWELlSbWZk8bH3ZixOPOAG4GflM9ef04+K9j0huJAYKSZuJt3Extv6JnTTzk7jHVfOoRzjamG3glcXPM6KB65v4e6QeMf4IOnP9Y+zE/VZM9aSZyKuxBbqvscEkpYL1W16Uf9/QAjLNcMnRqTu+gBQr8rc19iWEQcX7msSfZNAa11LGo0Gf154jtsxPH1lLPDuqkj8cvghDt0pQrE2AOtOP0WHBSeQkGl99V3D/WfvuWvRLD1s4yU8Tc7B0A0XC3Uee5AtU2LDmSjEpudZHmwCpUr/f+TAc6f8ID4LwzZeQnK2DADwz5WXZo/XYcFJDN5wEbde2v6dAYCsfAV6LzuLZccfY93pp4U6RmmQI1NCpny9xJJSVbpiJD4jH+O2XMPQjZd4//9svU/JzFfg3JNkqHl21Gg0eJmWW6bjnkiMFBMf7v+Q8zw2h9/9Ibm9A5hfEchmqWptjY2N3YF/P7N8stQo/eNfqgEn5ts22dwU28Yb4hYAvLOWKTTGEhBf/H2bO45tzWjwEVPZVOLI9G/pvQwYdpA7nmVZgoNBFVJ2QK+bv1XT3H8rHt/uuo2eS89YHsyCfZFOKVjECsvcfffwNCkHi44+snnfHJkSc/fdw4azUYhOtU6AZclK3mqk5eDteHyw5nyhxcScPXcxe+9dvLPSuJ6NXKnmvWgbkiPT/60kIuOqxE8NLCEioXWVi2+8TLdqHACo1RqceZSMlSeeoO7Mw/pzJ5t3ox66E4/JO24iX2GdKFCrNZj+3238dTFat+1hQhbOPErGtkvRHGFmjmyZEo3mHEGfZWetGv+qwP6/lBVBjGw8G4WpO29BpdZAo9Hg0rNUpOUYW5dTWdsUKuPvYnqubRbpj9ddwKC1F7CDRxAfuZuANj8ex7T/bvPsyU98Rj4Gro7Evptxuvlcepb62goaEiOFJDY7FqOPjkZkbKTV+4R6hKLni9tMAbK7/+lf0IoRa6t2pkVZHmOOnEKaF8uFAi3GAEP38r58L9FgwfRh+VPDuuormzo4A40+BtwMAnfZ1iK2JUTLkD1AjwVM6XYz3HyZjn4rzuK3c8/MjjPF0yT9IuLqqA+repSQhbY/HcP2Sy9sPqbCyoWCDduio3wF3UWjN19B5NMU/HL4gdlxf5x/jl5Lz+isE1qOF5i/4zK4VqM8uQqtfojAwDXG/1sypQp7b8ZiweEH0Gg0yJbrxRffJ+Qg5l7ihCbaKOQrVBj1+2Xdc8OF/fKzVLy3KpLXyrb3Vhw+Wn8BPx68z9nuKjUfkvfpH1ew7fILbD7/3Ow4LeeepOD3yOeYupNJuU/OlqHzr6fw0foLmPzPLY5IMcfFqBTIlGrcj8+ySvDxkZGrwNy9d3EntnAWpMKQy3J7FcUyMmvPXfx1MRpH7yXg5MMkvLsqEt2XnDYax/6q5PNYkZKz5bgba30hyxsF1rY9N41vVA8WWGA3n49Grty6G4p5++/hQlQqxm65CgDov/Ic3l0V+doGcpMYKSTfnvkWZ2PO4pMjn1g1/uumX2N3390IKvhSK/NZ1UQT7zIN6kqL0wusH+vio3/cZDjQdT5Tt0MLy+WTrzC4sGm73QKceJCMPAVepvHc6bPToSVO2HszFhvOsIRX6FtMPRITbDwbhR5LTuPDtRdwLTodF59Z745Kz5XjcWI28hUq3GFdYGLT83WL6De7buFFah6+/uem1cfVcjU6DW/9dBzH7pu+UDxOzMb5p3qr1cME/XdErlTjnysv8cnvl62+WJUW5u5SEzLzMe3f27gVk4EFBqLFVHulS89SkZwtx6Vn3PiXuIw81J91GOO2XMPSY49x6VkasvP1nwXfAmUoRsQGlhGNRoOP1l1AjWkHceSu/m9jeCf80foLuPgsFUMM3GAajQaHTbjy2EJWy7nHyWg27yjnXElWWt8y8hS6x2q1Bg/juRWJL0Txf98VKjUGb7iIhUeYKstpOfrj5Fj5XXqYkIX3VkXi3BMmMH/e/rtYdyYKPZbYZnVcEvEI762OtMoalCNT4viDRJ1FhB2Dk23BApiVrzDatuVCNNr8qC/qeC8uEycL4oMMBTHArXogU/B/x9edMe+K23n1JSZuu86x6vh7OBYcX38Cd0e9VZj9dzaHoetXexP17zX+elavOiRGCkl0lnV3IVU9q+L4e8fxUU1ua3pVHuuOYlMPYEPnok+KHXNhLS3GMt1qJz8DOvDEuQw/CHx2Dug8D2jBuJASMvOx69pL5uJvoq6JRqNh7lTf+4M5R9Vw7LjyEh1+OYH6sw6jw4KTSMoyuAhrLSlCCTQAxm25htl77+JxokEZeBPM2nMXd2IzC+WqaDE/AuELT6LGtIP48m99ps/Phx6gydyjyJOrkGdwAU3JluGbXbdw7jF/5tSms3oh9TQpB9GpuRi+6bLRuFy5ErdjMhC+8CTeX3NelzWQwjITy5VqTPr7Bg7fTcCf55nvnkypwszdd4occFkY2BdSbxcH3sUlJVuGFvMjdM+1f+/jDxJxOybDpJVCzTo220Kx6ewz5LMWhVy5Etky/YVbrlTj5st0zNx9R3dBN7QoCQ3ESEqOHGd4/n4KNXfx0Z6X/Tf5+/IL1Jt52GRMkrNEhDuxGRj751Wdu2jQugtIzJJxrDBagWTJvM6Oz82SKZFjECBr6vOMuJeAUw+TsCTiEV6m5XLEj9bNtezYI6w8YdoyO/bPq7j4LBWD1jI3TbdjLFsE4jLycNFAIC088hAXo1Kx82oMNBoN9t2MM3KlaRm/9RqGbbyEZceYZpvsz77n0jMmrRKbzkah7szDWHf6KbouOqWzkH6z6xZepuldirHpefBx018zDa2X7OdaMWE4V7VaA5Vag/NPU9D515NYdPQh5/WJ229g57UYbDz7TLfNx80RwzddQujU/ei++DTux2cikyWe2BagNaeeoP6swzqBoVazYktMfF1et1ggLZTaW0jYRc3MXUQ2d98MF0lBMCYrC0assG6BtZpmnwINP2TKqltL/Q+Q12EOFhx+gM61/dCM1X22Zf5SnPuiHgRaK4hvbd1rfZadRXxmPlKy5RjpURFIi4JCow8elCvV6Ln0NAI9nbBxWG+gVm8A4CzycqUam88/R5tq3mgaUlBrxMkT+PIxIHHkLPwbzz7Dteh0rP64MYK8eNw3VqBSa5CQmQ+pWIjyrsZ1SvJN3Plo+WbXLU58AgC8v+Y8HiVm43p0OvaPb2u0z8w9/JlK47ZcxYxetVHBjZnHoLUXcP1Fuu71l2l5CPJyRnqu/gLFtj5oL1abz0dj07ln2FRId5RGo4FSrYGEtco9TszCy7Q8pOcq0LWOHxwl/OmT7Ln9Fvkcu2/E4p/PWqG8ixQezsxd3rknKZy7y0vP0jDln5vYasHN9ThRf8HPV6rhKhLiRWquUdyMSChANutv8vOhB7rvTZ5chR8H1DOylhgu2KaypZQ8MQKGfLWDsZCZEr9KtQa9l52FSq3By/Q8/DeWv8+UWCjElgvR+PHgfWwc1hSNgsvxjmN/BzLzFLgfx12MhQLgxot0LDv+GFO71UDlCkzcFXtxa/PjcTQP1fdlypYpkZGrwC+HmUV0UPNguDuKjbqCPzf47CUGFqeDt+NwNy4Ln3eoColICI1Gg37LzyE+Mx//jW2NHJkSf7DcUdkyBSLuJepcDM9+6IE8uQpODvrv29F7jBtv6bHHGPVWZZ17SsucvXfx1yctdM81Gg0m/3MT2y8zMRlz990DAMzYfQeDW1aCITlyFdxY1qu49HwEl9dfX9ift/bxu6u4rkO1Bpi7765ObDxMeITxHath/Zko3f83AESxXL8pOXIcu8+8t7txmRj751WEeutj5PLkKlyLToO3qxTf72dcfxO2XUffhoHYfvkFpuy8hQnh1aAxoUYsWY1eVUiMFBK5ihXcpDZtVnPZMxHotYjpY8JqBifSFPMXpvtP0OSlQ3cJqdoJMdLKkDw7Dp+ch/z7OJXDmlNPse5MFNadicKzaUxdj2dqX8ShPLK9asNFrcFPhx6gfkUPdKvLBI7GF5gH5+67B+cWcxCcPB8/Kd8HwFzc/zj/HA8TsvEwIRsypcpkPYDFEY+wOOIRnnzfXR9Y6MqkOaezgiL/vMBYAmbvvYu1g5vwHsuS2Tc+Mx+tf2BMtM9+6AG1WoO7cZmo6e9uVVDjLgPTZ1qOHI8KFs27cdb7jQFg78047L0Zhy86VMXEzmEcIQIALlLm82Kba9nvT/t6fIblwNF8hYojKG68SIeTgwjJ2TIMWnsBgZ5O2Pt5G5RzcYBGo0H4wlO6sUOiK2Fq95o4ei8BbatW0IkMAEbxH2m5CnRYwBTci5rfHQKBgONm0r4fS0JErlTrFhHt/IUCoO1PxtWAc+UqjpuGLWDvxGVg/NZr+O861z9veAE3ZX63FAxqTaxFRp5CJ3ZuvEg3ece6OEIf3Nx/xTl8270mRr1V2WgcWwyn5cqx4Aj3/1ooFGDgmkjkK9Q4cjcBvw1vhrerVzA8DMedc/V5Gr77Vx80+e2uWzj/NAW7xrRGYpYM9Sp6MGKV9XZn/HcbuawFL3zhSZ2ArBvogU61fHE7JlN3ndh/Ow6rT3LdGU+TcpCYqf8O7br2EhO338CCd+ujf6OKRlaPATxBzoaf5x/nn+uEiCFPkoyDifPkKo5Yvf4ynSNG4lj/X9r/vxSDQFeVRsOxegDAwDXnjSxC7JgTw9ie2PR8zg3S0XsJWHT0kdF1KTErH1MKBNmio4/QuJJetLJviC89S8OKE48xpl1VZo5qjdWB2/aE3DSFRKHS/yPlmks1vbkVOLOIeawsWmaGORYdfYhmv+j92dc9OqL1lbfRLGUmNis78u/kHsitu+BSHv+En0Zn+U8AGLP66lNPserkE3z251UsP/7Y6CL8zXkhPlJ8i5saxoKy5tRTzNmrtwiwLzimSMmW4ceD9zHyt8u6RYB9560lOVuGWy8zdGPY/4CWznOTteD3WX4Wy48/Rs+lZzD9v9uFij5/62f94siOQzj7OBkLD1tXY2JJgfnZEIVKDY1Gw4nWH/vnVd3jdaejoNFo4GTCavHLoQf47t9bmLj9OmrPOIQTDxKh0WjwIjUXfZafRedfT+nM7THpeVh+nJmHodn/t8jnGL7pEsZtuYb6sw9j5m59mrk5V5g23uKFlRlAbAzv6sZsvsqJo2GTr1DpFjxDcmUqIyECGMeV8AUmAoDC4HvOrmGiVKl1wbfmMLRYhX13kH+gAfP238OKE8bfDbZLiu1u0CIUCDgWviEbLiIjTwFzX+9fDj+AnCW89t6MQ3K2HG1/Oo53Vp7DvAJhyHad/Rb5XCfEAa4lSxvQGsO6mXjKIwS2XnqBdax4sP9tuwGNhnFrAMDfV7ii9WGCsStHa61QqtSoO/MQpv/HUwahgHFbrhptO3Y/EbNZ16qTDxh3p1ypxtKIRxi/9brRuQy5ylPXx1CIAPraJHwo1WrO63sLsmMMrXbN5kVwnmfm8bt2AGDXVebmaebuO2g054ju77H98gv0WXYG8TwxMvaGLCOFRK6S6yLwVt9czTtGpP0HPv0LkPzQbPBlUdGmjkb4vQtFyjN8fjZA99pc5Uc4rm6AgaIT6Cy6ot/JIxBswZyvUOF4tBJyMHfADxOyOBkCPx96gKP3zEdqG2YUJGblW3StNPte/082YFUkVnzYiDdt7lp0OnotO4NWVcrjreoVsOFMFLZ/2hIh3i4Wi1l9xlrMb7xIx40CcfLnhehCReazLx4urKyJaf/extPkHCOztin47sDXnY7C2ceXkMk6B3vxj8/MR+STFDg68IuRZce5C9nQjZcQ6OmE95oE8Y5fdyYK4bV8EejpZPTauSd6IbDp3DN826MmxEIB1rMDiw0Y8+dVLBxY36RQMEeOgRi5+CwVFzfxxyXlylUm67fwLdYAsPNqDIa2CoG7owRpuXKTlhHt9vRcOV6m5XEsKsnZcoz4zTj2pzj56eADtK1aAXUreuBlWi6m/3eHYymLfGIs0Phufv+6GG0UtMvG3GsA8zef2bu2qfAEI+7GMvEPB27H6bYVJuBaYqKAHRuZUg2VWoMNZ6PMLvYAcD/esls8KVuGO7EZWHniiU4QaHmcmI2fDK5tAH/gKx/m0t8VKg2esASdo8Q6G0EUK3WcLQ61zzUajU4Q77r6EuM6VMPXBa7FEb9dQmqOHHEZ+ehR1x/LP2xk1TlLEhIjhUTD8qluvreZ81pVuRxPHKRYGV+wcKuVwJ2dzE8xEa8pBz+BsSpf6zwC5+MNTISQIkLdGMfUDRElYgXSulfk+ND/t+06DtzWZwacfGgc2HctOt2meSYUWCysTSG8/iIdrX44ZnbMuScpukVy3v57WDu4CQ7fLXw6298WCmFZQnvxUKjUutoSN60smsVXP4T9NzDFoHW2ZV/FpOfh16Mm3HVg4l/m9K1j8Thz9t6Fg0ioq23Ax9F7Cfjp4H3d394WrM3uALRZWfwXebkJN0t0ai4++eMKKrhKse9WHGb04i/nffxBIr7pXgM9lpzh3OUD4ATlliRpuXI8TcrWub/Y/MGTDsz3L/bDAeMFlI219TrUVloPD99NQLN5RzkWGlOCzxzWpMLnK1T48eB9rDlVPMXl7sRkmMwO0i7ihcWSaGF/X6011LKDs7/eYdxeYzIr68/NUYII1o0kO2Nw3604ND4ThX4NA1HOxX7tEkiMlACj0zLQWiWGq6zwbpkL6hpoLuReSO6rg1BDyJgvNyvD8aXkb6P9zj81nc6qMfDK/fXMBUKh/m7LcBG0ZG2wBq2pvqSKcSVk5iMzX4GdV4smKIqCUqXBjRfpmLlHbyY2VZrcED6Trr2YxoodMMXvkdbVxNh83rpsMy3xGfk2l9e2tNCagv2ZzzIRZByVnINui08bCZHSJCo5B4NtqKi7l6d+hSUMYyD4yFeorF4gmfEGNVpsbFHw3/UYozgMPmRKdbEJEcC6z6KwWJuuC3CFAh8+blIkFmSmSUQCKFQanRvL2UGkc9mw42dy5Sqz1rzZe+/i7ONkrB/K03y1lKCYkRJAAsBVZnu2zEplL93jXI1xxsd0xVDd4xS4I09ju4p9qA4EAAyVf42p+6J4Kw9q4fOH2srNmAw8TcrGPRuDPK0+/ssM9Ft+FjKlGn7ujmhSiT8ToSSRKdXou+Isx2r0IMG6v/8UgwyBskqL+RH4asdNXYbKq4Ch6bu48XY1//+7+iR/qq2pWCFLGWGF5XlKCXT2NgM7VsMctizwJUVVH1fLg4qZyhX0rTK+7BzGec1BLMRP79Qz2icjTwGp2PxyH3E/0a7VW0mMFAYLfzBb4pZ3qJhU3GSNO1axxIgcEnwkn4r76iDcUFfG5/JxyIVeoMRpvLBR1RUAcERlvb9vsHwKbnbehhPqBgCYL6ApiqPq576bceiwgKmfUVJoI+VDvV1QsZxx3ENJky1T2nTnSLwZFLVja72KnmZfjzVh2h/YVB/706pK+UKd+1OebB1TdFl0yvIgAMNahxRqLoXFMNarXVgF7BzTysRoPc1Yqc1FZXaf2pYHFTPszBtDMaRUaTgZQVoeJWRZ5ZJLzi4565AlSIwUBrV5l4Mt69JPioGYrBiFvvI5yIf+TkkNAc6o66Kr/Ef0kc/FHnUr5LHESLymPH5VDsDH8in4QjHO6vPFozweSS3HBryOqDQaOFsowV2cdK/rV2rnIl4twnzdUL6I/nU/j0IUKQTQorJ+MQ32csavA+sbjWkQ5Gn+GFXKw9lEALStuDiIcGjCW+hcy77/D65SMRoFl8MKM8GYtQPczb5uC7vGtELDoHJwlYoR5FX0m6Budaz7/Pzd9d8bfw/ueR3EQvi4GVvVzd10snlkpUW3JCAxYgsaDW7u+QxRJ+eZH2bDIVPhhm2q9nipqQAZ9HUcNDz2Ffa2OI0XFBDjtLoe8mDbRS0hq3TSuqwxYdYP8sT6IU3Quir/Hd79OV1x6dtwq843ok0oJ6Pg2rROZt02DYM9rTquKSrwFE+zxAfNgnWPbbk7tQVzFzVrY1kMmdiputnXd4xuafWxouZ3x6i2oZYH2kDjSuXQr2FgsR6zUy1fk6+tH9rEotnbEj3q+uOdRhVt3q9iOf2dr4+bFD3qBhiN0daiYbOStQiLBALU8ne3+dyG9Kjrj+2jWyLMzw0eThLLO5Qg2uwzw+8/+xrg7SqFi4PtNyz9eb5bNf3d4eQgQuTUDjgw/i3s/8K48KE1uErFODihLapU4F4vXQrE4qdvV+a8pwBW1pu/gaB1EAmNBIolqvm4YmavWlj8fgNU93OzdfrFBokRG0h9eQEfpp5B7xf/mB1njRiZr/gA3yqGQ8mJIdavpHzHiNF4I1PjhCSNOzLgwjPCOuLSS1aMjGlXBcNbh6J2gOWL3eOELHSs6WuUJ6/FUSKCp7Pli9zOMa3QpbYfkrP0ZkZPZ4nZYj/9C7EQsKnAcwfCx4fNg7H4/QY4O6UD5vevq9uuUmvM3l2H1/SFdyEEj687vzit7O2CQ/97izeFl4+ONfR9iSwJS09nB6MLoykEAkGhK+ma4p/PWmFq9xrFdrxDE95CazMuEG9XqVHfGy0rzdx5z2VlLJVzdsC0njV5x5la2Ps3CkR5VqxJBTdmHnMNMqGcJMYLbpifG9wLKo7W9HeHp7Ntlp1P366MD5rpXUQdavhg+YeNUDvAAwDg7mTffAht3Q3D6rHs91ne1cFi6uyyQQ2NtvFlmmmFvZujBK5ScaEtXTdmdEYNP3dO9VkAmNK9JrZ90gITO1XnuJ/Z10PDa2NweWc4OYiwjVWZ1hLVfF0xtHUo+jQILNT1prggMWIDcdn86YzD0jMxNi1d99yUGOkq+wHzFR+gq+wHrFb1wp8q03f8hpkvACCDA1rKlqGNbAn4IlNqWnmnw5cWWBguftPRKEajZz1/fN21Bqb3qsV7QV03uAkncK9jTebus26gh8nzSERCTtlmPrQltBNZVh+BQICGJkprA0AFngDCgTy1OOoEumPhe8amcGsv5vP61UWfBoFGIkCp1mDzyOYcszub5R825NRb8XXnXigGNgniFQmmxMjfo1si1NsFZ6d0wMO53bD4/QZm581O8+MTTeyFyUUqsrrmAmA6CFOLmw3uNomI+V/wcXPE6a/b4+q0TkZjAj2dUL+i6e+YIWF+bviwRSW810QvWF1Yi4VULORUFmZr3hqs/0P2HfXez9twSrE7SoRwZt2lb/2kBf75rBVm9qqF69M7IWp+d/1xGgVi6QcNMa9vXXix/hZOBfv3qheAQc2D8Xb1CviiQ1VeF0yApxNOf90BZya3RwU3qU6YWMuotpXRpqq+oms9g8/TkmWksFY5awnhiZUAuNWLK7hKIRAIsGmY6awRP4P/nwGNK8JFKsaKDxtxYnQM+xyxLWU1/Nzg4yZFB5agN4X2hsnwb9YsxAvNK5eHVCzCuA7V0Kt+ADYMbYIutf1Q2dsF7zSqaCS8fiwIXm1euTzuz+mK41+2MzrfWwZVeVPsGCfCxuZvx6lTp9CrVy8EBARAIBDg33//tbjPiRMn0KhRI0ilUlStWhWbNm0qxFTtz/Nk/loWDWQyjE7XZ4uww4RWK3sAAP5RtcF9TTBWq3rhviYYljAlaHLgBBmMF4Zvu9fEqo9s84Wy3RTfdue/QzNFr/oB8HF35PwDnvqqPRa/r7+r4Ls4VfRyQgVWcyptnYf/hVdHlQqmrT3mLnTsO53e9RmTtfa9fdGxqsn93q7ug5DyzqhX0QO1A9zxfb+66FhTf/H4vENVhNf0wY7RrXitKJYEEsAfLDe4ZSW4SsUY2TYUNf3d8cu7xkIHAKRiET7vUA0A0zOkTgD34j+0dQiO/M+4F1GrKuV5L/zsRcxBLESfBubdGuzxzjymbfaFkO91Q+oGeuisBpaE3LSetfDp25U5liRTsM8d5OXMmXev+gEo5yzB4vcbYPvollYXlAIYEfwjKzOhdVVv3WOBQAAp61jsej1BLIGuYkU21/R35wgYJwcRHMRCdK3th1ZVyqNJpXJoXKkchrYOhUAg4Hy+DiIhetUPgJODiHMM1wLR5uEswff96uK34c0wsXMY5/rxXY+a+PGdunCUiODhLNG5eQwXU3P8L7w6vF2lnM/PUIy4SsVmi6jN7F0b5Qzu5DvW8OFY4CxhKBS0DGhcEd/04L+G1fTXux601sx2YT549kMPjGlXBe6OYo4wZ19rwnzdMKcPYxXpXtffbNAy+1r4XpMgXPw2HE1CuDdDhu4etrhhC/RNw5oijOUy8XCSYOkHDdGhhi9cpGJETHobCwpukOoEMuK3ddXyCPXWX0MdJSJea2VTA9c1u3iaPbHZrpaTk4P69etj+PDh6N+/v8XxUVFR6NGjB0aPHo0///wTERERGDlyJPz9/dGlS5dCTdpeZOfzp7o6F3T4rCKX44mDA5rn6+uLLFC+hzPqurikDuPdl02zEC+goNSHq6MEsCFzbdRblTm9GgI9nXQ1EsZ3rMbpf6GlfZgPFg9siGsv0tCrXgBuvEw3qjxoiINYiH4NAnX/+A6sC6Ovh5TjFuETEFrT9JANF/FVlzBdZHg5Fwd81SUMozcbl20G+Ium7fuiDb7ecROj2upjLz5qUQkh3i46i4izgxgj24Ri3ZkoNAz2RJivm64/ipODCMcmtYNAoF9Y2cW8JhmkzZ36qj2nDLy7FT7yZR8Ym3xn96mD73rU0pn5+ZrRjWjDxFSM61AV7cIqoFaAO5ZEPOIEork4MA3NXBxEulLuxya9jcoVXPHTgHqISc9DUpZMV4XR8C4KAH55tz6m/XsbkzpXx0+HHmBIy0q4H58F9wLTs/69Gl8qAlgXOmcHEZZ80BA/HrjPqc1Rw89NV/1yz+dtdNstubj8PBzxXtMgqNQaowZphvC5AzcObYrbMRkY14ERo9r33r9RRWy5wK2B8mXn6rpGcQDQt4E+BkMgEOCfz1ohMTMfAoGAU1yP/Z1c/H5DjN1yFV90rAYxSwgObBKE5ym5CPV2gUgogJClhbSLz6qPG5t8b3UDPXArJsMoHmZs+yq4+TLD5J03u0jZSNb/R2Ep58J819kZdobZQAKBABGT3sb+W/FGlZgBIMzPFVendcLRe4m6rsUCgfXuTgDo0yAAq089RUh5ZzxjpRybEvQA8H6zYKw9zVQMrm8Q2Pt11xqY1DmMsyC7sm4y3msaxHGf1PR3xzfda/BaH9l/d20jQXb6cZNK5TCvX134uDuiRWUvJGTmo0ttfSwI+zyWXD7s/+W1g5vg78svOfFoWviuLaPeqgyBgLGQJ2TK0KOev9lzlRY2i5Fu3bqhW7duVo9ftWoVQkNDsWDBAgBAzZo1cebMGfz6668mxYhMJoOMVTAsM7NkalTYSpaMv6pmiIIJnNoREw+ZQACXggtBjkYKOSQ4rTbO+wYYlXzuSYqubPa6oU2AH5jXpDw+X0tIxSLUq+iB2PQ87PisJR4nZqNKBVd4uTigWagXPjSo2lnOxQHB5Z11qWADmwYZiZEPmgXrGjvV8HPDwQncO3H2jZBEyL3r5FusPZ0laFXFG7dmdjH6RzH0wbNN5N/3r4uhGy8BYC7QfRsGonaAB/YZBI2JRUK0C+NeoL/sEoZ6QZ5oW9Ubqw2KJBneHWrvVKr7Grs/gss7o1f9AOy5wRSXcneUoG01b5x+ZFypVouPiTs59nvlc1lo78BEQoHuAjqmXVUsZfWz0V40T0/ugEZzjnDO17dg8Zq3j7+ol5YBjSuiX8NAiIQCfNSiEudvMptVEIztYmpT1Rvz+tVBxD29MJKIhOhdPwC96wcgZMo+AMyCWdnbFZNY3Zq18C1AXWv7wclBhIcJWTqLkkgowMxetXDmcQqO3ktADT83/DWqBQ7fjcex+4nQaJg7bkPa1/BBe56Fun2Yj06MlHdxwJy+ddC9rr9OjAgEwIL3GnD20TYk02g0mNipus4iwG7M172uH27M6KwT4Ce+bIeHCVloVdUb/7IsKmwLiqkGkmy2f9oSsRl5RsGNX3UxHx9T1HoRlb1dMK1nLQzbxPzP+RRYM9kxBXzxBZXKu5h0uTpKRBAIBAhnWR+zZUrO3bwlAjydcOnbcLhKxagz85DJrstaqvq4cr5rfHMTCQUcIeDsIEa7sAo4/zQFfRoYBwd/8lYVi/N0KHAdPk/WC6YdnzFpx1O68f/t2BY+Ryu+G1r8PZzwRcdqJl9fO7gJ7sVlwkEshLujBI4Sxu3zccsQHL2bgK5WZvGUNCUecRQZGYnwcG5sRJcuXTBhwgST+8yfPx+zZs0q4ZnZTrbMWBStjkuEQOkGCNIhBiDWaHBLHYK6wmcYrfif0fgKblJMCK+GD5szLa2/3nFDVymPvShliI2D5z59u7Ku+2WX2r44dMfYbfTPZ62Qr1DBzVHCiapmm5i1GMYB8F1cPmwejLere+OfqzH4ZYDx3Qe7oZ3hws42qc7sVYtjpuZT7A4i/bYto5qjZWX9Z8COjZjarQZa8bwfUzhKRDr3zWdvV8HV52m6xdqQci4OuDmzs8mYBrYrycNJjPVDmmL1ySdYcOQhJCIBzk7uwOm1Y+38rMHJQYR2YRVwoqChl9bk7eXigF8H1odaDY41A+C3hhiitWYZzoPdtZR919cw2BOVyrtYLNktgAB9GgTg/NMUtKjM/T7zFfya268O73dwaOtQDG0dimfJOXBzFKOciwMGNg3GwKaW3Z2GhPnqTd9np3Qwes8da/iaDHoWCASci36dgoVNKhZCIBBwLIEh3i4I4Vlk/T0c0aOuP5wcREYBi3w4OYiMhIg1FEWLNAr2xD+ftUJ6rgLODiJULOeks8A0CvbEL+/W53yOhpjqTqxdbNnfyRyZCmk8TTG1NA/1Qq/6AbrOwmxLilQsNBn4rkUsFMDdUYKtn7SAk0Rk8n/N390RjSuVg0QkgLsj838tU6qscj/yoRVvI9uG4tDdeAxuUcniPuyYEWuvCdbQqZYvb2aYh5ME7zQuWhB/cVLiYiQ+Ph6+vtwPwtfXF5mZmcjLy4OTk3Fk/9SpUzFx4kTd88zMTAQF8Tf5KhUS7wErWsDVww3w4vrbWuXn47g6DL6idN225cq+OKuugywYB1Rd/KYj55/xm+41oVRpMKBJRUhEQoyWT0A/0Rns9fgI05qF6DrgVvd1RYcwH50YaVG5PIK9nLH2dBTah+kDkiQiockmU7vGtEK/FfpW3OUM/PY1/d2xaGADBHk5QSwUIiY9D3UCPVAn0ANd6/Cb8lJyTJe8b1PVG9N7MoGs/RsFWlwY2dYCHzdHznj23Y2pTqvW4OEswXYLaajujqbdL2w/ubujBA5iIca0r4pyLg4o5+xg0hJiDlvae7MvWOzPp1/D4r+o9KwXgAO343V3k78Pb4b9t+Iw+m3mztCSGHFyEEEsEuJnHhM6n1XAUsol3+JuK8HlnbF8UCO4O4k5F/yF79XH6pNP8Z2JuAM+vF2lOD+1I28arSkEAkGpNCWrbCb+Soup+AuAmWc5FwdETu0IqVio+98UCAQYYGEBq+ajFyo/Dain6+vCF6+TI1OiRz1/7DDRH+rrrjXQuFI5nRhhi+3v+9XFhG3XzVoFtP9bhmLYEKFQoEtPFwgEEAmsi4MyZMG79XE3LhPtCq7JTUK8cH1aZ6syjdjXbVtim94UXsneNFKpFFKp/VKMDJGfWYqrjlLEiY0/rlHyifAUZKO9SG+KFkDDK0TOTunAm3a2cGAD3fOD6mY4qG6GcLEbRrQJxTuNArHjyks0DPbkfFn9PRwxqHkwmoeWR3MT2RiGGGaW8KXMsi0Ghv5VPjydHBCv4M+iEAoFGN7G+noSbDFieIFnL17FeddgK2w/udYNpXVxaBEK+JuWWctPA/jdegAwuWsN5MlVVpmKAcsZDuboXtcP/3zWEtUL7oLfql6BE4nfLswHvxx+aGRhm9SpOg7eicfHLc3fDc7pUxv7bsXp+imV1gWYz0fev1HFQqV6Fzads6QZ274qcmQqszVnPn27Mp4kZZttzFiY709weWfs/bwNKrhJ4SgR6cQIn+jOkinRPswHV6d10rkavV2lSM5mbnK0gdhfdQnDhahUzt+ub8NAtK7qbbasvqWuxGyssSJa4p3GFfGOwTYPK0oTAFyXtz2vcfaixMWIn58fEhK47oSEhAS4u7vzWkVeRdYl3sFKf/4CSEfUTSAVA56KbHwr2QKAESNamoV64WJUKgI9nayu7wAAWt3h6eygC0B7yKqO5+fhBKlYhHAzhZn4CPBwRGxGPrxdHcyaWq1lxUeNMOO/O0UujW2IC09q59IPGuJObCbHfVPaeLtKsbEgLdDUBUMiElrdDdWQCeHV8B5PerGWSuVdsHFYM6uPN6x1CC5GpRbKLywQCNC4kmmhWyfQA0cnvmVkDfq8YzV8buZuVcvHLUPwccsQbDobBU9nh2JZDAgGZwcxbywNGzdHCVZ+1FgX46MluBhqwNRhxWb0axgIpVrDKRI4qHkwtlyIxoRw5nvCzoASCYEf+tfFs5RcXabI2PZVMba98XlMBb/2qOePfTfj8Fk709l0rxoCTjwRWUaKnZYtW2L//v2cbUeOHEHLltZXbLQ3h0TJMJcF7e/hjLUpPXViREv7sAr44Z16WHPqKefO2RrEQuPzsdM1zZlYzbF9dEtEJeegbbUKlgdbQaPgcpwsiaKgZJn9nXkW+l71A9CrvnFAWWnTPsx8KuK3PWpi+n93MLRViM3HFtjU2cgyzg5i/DbcevFiK1V9ii5oh7Yu3mqshG38L7w6fj36EFUquKCmvzu+K+Ybi19Zll8tc/rUwYg2oajM43oTCQR4nyczxBaWvN8QU7rWKPbieiVJLX93SMVC+Hk4lklhbrMYyc7OxuPH+oj+qKgoXL9+HV5eXggODsbUqVMRExOD33//HQAwevRoLFu2DF9//TWGDx+OY8eOYfv27di3b5+pU7wyHH+QiP2HDkDopAR4antoGdehGr78+wZSNa7wEmSjQZtuqCT0wtj2VeEqFRfKasBXA4Cdcmap46cpKpZz5pSTfpVg3+WIS7hAUknycYtKeKtaBZvuMD9qEYz9t+LxYYuiXYQJwlY+71AVXer4opqPm03xS0VBJBSYDMwViYo+B5Gw+Kv8ljRODiJcn94Z4mJ4/68jNouRy5cvo317vb1MG2g6ZMgQbNq0CXFxcYiO1ufxh4aGYt++ffjf//6HxYsXo2LFili3bt1rUWNkxqa9OCX9H3oFcn3MGqULBGImL/32rC5wKShe1OqvpXBFPmZWDMEn9Qp3B6+NN2jLky3i7SrF6o8bw00qfq0Xa1NUKu+CpR80LHIDMnsjEAhsDrac27cuZvWuU2qLAUFoEQoFqOFX9D41RWVu3zr44cB9LBpoXJunrGBNhtWbikBT1IT0UiAzMxMeHh7IyMiAu3vp/dP8O68eLnpk46iLE/JYbhN5WjM4lLsIALg1RF+QSet7XTaoIXoWUoy8SM3F1WimCJktFRIJgiBed9RqDV333jCsXb9fyWyaV4WZgWqoBMZ3uBt6z8Kv5zfh/brGPTCAogWABXk5v3bmRYIgiOKAhEjZhcSIGVQGQUTLOy5HgEsAqpariNaVvzMav/3TlohOzTUqk0wQBEEQhGlIjNhAS/+WkIhM54w3C/XibYxGEARBEIRp3rwoyGLEwaBylTkhQhAEQRBE4SAxwkOeXIV5++6iqtyGtrkEQRAEQRQKEiM8HDkegfcv9IeSYqkIgiAIosQhMcJDhRcHUUUYB3lBAGuHoPb4q8dfdp4VQRAEQbyZUAArD0qFHACQX5Bm9km9T1Hb23yfB4IgCIIgCgeJERYZeQrcic0AFEx1Va1lxEH0elcEJQiCIIhXGRIjLAasPIdHidn4SZwCiAFZgRhxFL2abcIJgiAI4k2AxAiLzMRo9BbeRyVhAgC9GCHLCEEQBEGUHCRGWByQToGXIBsaAA8cJFAWiBGpSGp+R4IgCIIgCg1l07DwEmQDAI46O2EAq1MvWUYIgiAIouQgMcLDAweu+CDLCEEQBEGUHCRGeMgScj8WkVBkp5kQBEEQxJsPiREeDMUIQRAEQRAlB626PGQJqQ48QRAEQZQWJEYMSBSJcMLF2d7TIAiCIIgyA4kRA7a6u3KeL26/2E4zIQiCIIiyAdUZMUCi0egeb+iyAU39mtpxNgRBEATx5kOWETPUr1Df3lMgCIIgiDceEiMG5BRk0gyt9h4VOyMIgiCIUoDEiAHZAuYjcXX2tvNMCIIgCKJsQGLEgOyCtF5XqbudZ0IQBEEQZQMKYC1ApdZAKQCuOTKl310lrhb2IAiCIAiiOCDLSAEKpQqf+fogUczoMxIjBEEQBFE6kBgpQKlU4JKTo+65s4QKnxEEQRBEaUBipAClQsZ57iR2stNMCIIgCKJsQWKkAKVCwXlOYoQgCIIgSgcSIwUolWQZIQiCIAh7QGKkAJVcznlOYoQgCIIgSgcSIwUoFSRGCIIgCMIekBgpQKXkihFHsaOJkQRBEARBFCeFEiPLly9HSEgIHB0d0bx5c1y8eNHs+EWLFiEsLAxOTk4ICgrC//73P+Tn5xdqwiWFXM6NGRELqR4cQRAEQZQGNouRbdu2YeLEiZgxYwauXr2K+vXro0uXLkhMTOQdv2XLFkyZMgUzZszAvXv3sH79emzbtg3ffPNNkSdfnNx8lmDvKRAEQRBEmcRmMbJw4UKMGjUKw4YNQ61atbBq1So4Oztjw4YNvOPPnTuH1q1bY9CgQQgJCUHnzp3xwQcfmLWmyGQyZGZmcn5Kksx8BV6c31Wi5yAIgiAIgh+bxIhcLseVK1cQHh6uP4BQiPDwcERGRvLu06pVK1y5ckUnPp4+fYr9+/eje/fuJs8zf/58eHh46H6CgoJsmabNZKUnY5JkR4megyAIgiAIfmwKjEhOToZKpYKvry9nu6+vL+7fv8+7z6BBg5CcnIw2bdpAo9FAqVRi9OjRZt00U6dOxcSJE3XPMzMzS1SQiORZnOdN/ZqW2LkIgiAIguBS4tk0J06cwPfff48VK1bg6tWr2LlzJ/bt24c5c+aY3EcqlcLd3Z3zU5Io1RoAgEDD/P6x7Y8lej6CIAiCIPTYZBnx9vaGSCRCQgI32DMhIQF+fn68+0ybNg0ff/wxRo4cCQCoW7cucnJy8Mknn+Dbb7+FUGj/7GKlQg4VAI1AAABwEDnYd0IEQRAEUYawSQk4ODigcePGiIiI0G1Tq9WIiIhAy5YteffJzc01EhwikQgAoCmwRNgbpVwORYEQASitlyAIgiBKE5tX3YkTJ2LIkCFo0qQJmjVrhkWLFiEnJwfDhg0DAAwePBiBgYGYP38+AKBXr15YuHAhGjZsiObNm+Px48eYNm0aevXqpRMl9kalkEHJei4RSuw2F4IgCIIoa9gsRgYOHIikpCRMnz4d8fHxaNCgAQ4ePKgLao2OjuZYQr777jsIBAJ89913iImJQYUKFdCrVy/Mmzev+N5FEVEpZWQZIQiCIAg7IdC8Kr4SM2RmZsLDwwMZGRklEsx6K/IgfI8OQsfgQAg1GtwYervYz0EQBEEQZQ1r12/7R4++AqiVcigLDCPiV16aEQRBEMSbBYkRACqFHAowaoSiRQiCIAiidCExAq5lhMQIQRAEQZQuJEbAiBGZtsaIYzk7z4YgCIIgyhYkRsCIkeXlPAEAUqmbfSdDEARBEGUMEiMA0uRpOOXsBAAQQGBhNEEQBEEQxQmJEQAKVb7usQaUTkMQBEEQpQmJEQBqlVz/WKO240wIgiAIouxBYgSAUimz9xQIgiAIosxCYgSAQq0XI2QZIQiCIIjShcQIAKWKxAhBEARB2AsSIwCUGn3MyGvQqocgCIIg3ihIjABQsgNYQZYRgiAIgihNSIwAUGoUusfkpiEIgiCI0oXECAAVS4yQm4YgCIIgShcSIwCUapZlhNw0BEEQBFGqkBgBoIRejAjpIyEIgiCIUoVWXgAqjVL3eEG7BXacCUEQBEGUPUiMAFCBESPNRJXQ1K+pnWdDEARBEGULEiMAlBoVAMBB6GDnmRAEQRBE2YPECAAVGDEiEUjsPBOCIAiCKHuQGAGgEhSIERFZRgiCIAiitCExArabhiwjBEEQBFHakBgBoBIwtUXIMkIQBEEQpQ+JEQCqgkJnDiKpnWdCEARBEGUPEiMAlAKmBLyDmMQIQRAEQZQ2JEYAKAvcNFKRo51nQhAEQRBlDxIjAJQosIxIyDJCEARBEKUNiRHo3TRSsZOdZ0IQBEEQZQ8SI9CLEUcJiRGCIAiCKG1IjABQCpjfjhJn+06EIAiCIMogZV6MaDQalmWEAlgJgiAIorQp82JEoVRDUWAZcZKSZYQgCIIgSptCiZHly5cjJCQEjo6OaN68OS5evGh2fHp6OsaOHQt/f39IpVJUr14d+/fvL9SEixuFUgGFgFEjTg6udp4NQRAEQZQ9xLbusG3bNkycOBGrVq1C8+bNsWjRInTp0gUPHjyAj4+P0Xi5XI5OnTrBx8cHO3bsQGBgIJ4/fw5PT8/imH+RUchlkGvFCFlGCIIgCKLUsVmMLFy4EKNGjcKwYcMAAKtWrcK+ffuwYcMGTJkyxWj8hg0bkJqainPnzkEiYRrRhYSEFG3WxYhCIYMcjBhxJMsIQRAEQZQ6Nrlp5HI5rly5gvDwcP0BhEKEh4cjMjKSd5/du3ejZcuWGDt2LHx9fVGnTh18//33UKlUJs8jk8mQmZnJ+SkplCzLiAOl9hIEQRBEqWOTGElOToZKpYKvry9nu6+vL+Lj43n3efr0KXbs2AGVSoX9+/dj2rRpWLBgAebOnWvyPPPnz4eHh4fuJygoyJZp2gQjRpjH1JuGIAiCIEqfEs+mUavV8PHxwZo1a9C4cWMMHDgQ3377LVatWmVyn6lTpyIjI0P38+LFixKbn0Ker7eMCB1K7DwEQRAEQfBjU8yIt7c3RCIREhISONsTEhLg5+fHu4+/vz8kEglEIpFuW82aNREfHw+5XA4HB2MBIJVKIZWWjpVCJs+FRitGRCRGCIIgCKK0scky4uDggMaNGyMiIkK3Ta1WIyIiAi1btuTdp3Xr1nj8+DHUarVu28OHD+Hv788rREqbfHmu7jGJEYIgCIIofWx200ycOBFr167Fb7/9hnv37uGzzz5DTk6OLrtm8ODBmDp1qm78Z599htTUVIwfPx4PHz7Evn378P3332Ps2LHF9y6KgEyeo3tMbhqCIAiCKH1sTu0dOHAgkpKSMH36dMTHx6NBgwY4ePCgLqg1OjoaQqFe4wQFBeHQoUP43//+h3r16iEwMBDjx4/H5MmTi+9dFAGZgrGMCDUaiIQiC6MJgiAIgihuBBqNRmPvSVgiMzMTHh4eyMjIgLu7e7Ee+/Cx3zDpxS+QqjW4POx2sR6bIAiCIMoy1q7fZb43jUyRDwCQaAR2nglBEARBlE3KvBiRKwvEiJ3nQRAEQRBlFRIjyjwAgJgsIwRBEARhF0iMFFhGxCAxQhAEQRD2oMyLEYVKGzNS5j8KgiAIgrALZX4FVqhlAMgyQhAEQRD2osyLEaVKDgAQ00dBEARBEHahzK/AKnWBGCE3DUEQBEHYhTK/Ais0SgCAhD4KgiAIgrALZX4FVhaIEXLTEARBEIR9KPMrsErNiBEhfRQEQRAEYRfK/AqsKrCMiARl/qMgCIIgCLtQ5ldgFdQAACGl9hIEQRCEXSjzYkSjUQEgNw1BEARB2IsyvwKrtWJEILLzTAiCIAiibEJiRKN105T5j4IgCIIg7EKZX4HV0FpGyvxHQRAEQRB2ocyvwFrLCGXTEARBEIR9KPMrsLogm0ZAMSMEQRAEYRdIjBQEsIpAYoQgCIIg7EGZFyMaaABQzAhBEARB2IsyvwJr3TQictMQBEEQhF0gMaJN7SUxQhAEQRB2gcQISIwQBEEQhD0hMUJuGoIgCIKwKyRGtAGsQhIjBEEQBGEPSIwUiBGRQGznmRAEQRBE2aTMixGNNmaELCMEQRAEYRfKvBjRWkbEQrKMEARBEIQ9KPNiRKNz05BlhCAIgiDsQZkXI/oAVrKMEARBEIQ9IDGitYyIJHaeCUEQBEGUTUiMCApiRiibhiAIgiDsQqHEyPLlyxESEgJHR0c0b94cFy9etGq/rVu3QiAQoG/fvoU5bYmgs4yQm4YgCIIg7ILNYmTbtm2YOHEiZsyYgatXr6J+/fro0qULEhMTze737NkzfPnll2jbtm2hJ1sS6MUIuWkIgiAIwh7YLEYWLlyIUaNGYdiwYahVqxZWrVoFZ2dnbNiwweQ+KpUKH374IWbNmoXKlSsXacLFjVrA/BaLyDJCEARBEPbAJjEil8tx5coVhIeH6w8gFCI8PByRkZEm95s9ezZ8fHwwYsQIq84jk8mQmZnJ+SkpKICVIAiCIOyLTWIkOTkZKpUKvr6+nO2+vr6Ij4/n3efMmTNYv3491q5da/V55s+fDw8PD91PUFCQLdO0CXXBbyp6RhAEQRD2oUSzabKysvDxxx9j7dq18Pb2tnq/qVOnIiMjQ/fz4sWLEpujSptNI3IosXMQBEEQBGEam8wB3t7eEIlESEhI4GxPSEiAn5+f0fgnT57g2bNn6NWrl26bWs3YIsRiMR48eIAqVaoY7SeVSiGVSm2ZWqHRFPwWUcwIQRAEQdgFmywjDg4OaNy4MSIiInTb1Go1IiIi0LJlS6PxNWrUwK1bt3D9+nXdT+/evdG+fXtcv369RN0v1qIq+C0RkmWEIAiCIOyBzeaAiRMnYsiQIWjSpAmaNWuGRYsWIScnB8OGDQMADB48GIGBgZg/fz4cHR1Rp04dzv6enp4AYLTdXmiLnonEFMBKEARBEPbAZjEycOBAJCUlYfr06YiPj0eDBg1w8OBBXVBrdHQ0hMLXp7CrNoBVQjEjBEEQBGEXBBqNRmN5mH3JzMyEh4cHMjIy4O7uXqzH7rC+FpLEIqxoOA9t6/Uu1mMTBEEQRFnG2vX79TFhlBC61F6yjBAEQRCEXSjzYkSlrcBKMSMEQRAEYRfKtBhRqzVQg1EjFDNCEARBEPahTIsRlUajs4w4iB3tOxmCIAiCKKOUbTGiUuljRshNQxAEQRB2oWyLEaUCSgFjGiHLCEEQBEHYhzItRpRKhb4Cq4QsIwRBEARhD8q4GFFCrbOMlE4vHIIgCIIguJRtMaKQ6R47SMhNQxAEQRD2oEyLEbkyX/dYKCQ3DUEQBEHYgzItRhRKue6xSERihCAIgiDsQZkWI0ql3k0jEorsOBOCIAiCKLuUaTGiULAsIwISIwRBEARhD8q2GFGxLCMkRgiCIAjCLpRpMaJUKQAAQo0GgoIUX4IgCIIgSpcyLUa0AaxkEyEIgiAI+1GmxYiyQIwINXaeCEEQBEGUYcq2GFGRZYQgCIIg7I3Y3hOwJ0q1NmbEzhMhCIIoRVQqFRQKhb2nQbwBSCQSiERFv6Uv22KkIICVLCMEQZQFNBoN4uPjkZ6ebu+pEG8Qnp6e8PPzK1IiSJkWI6oCN02Z9lURBFFm0AoRHx8fODs7UxYhUSQ0Gg1yc3ORmJgIAPD39y/0scq0GNGn9tp5IgRBECWMSqXSCZHy5cvbezrEG4KTkxMAIDExET4+PoV22ZRpo4BK56ahuwOCIN5stDEizs7Odp4J8aah/U4VJQ6JxAjK+IdAEESZglwzRHFTHN+pMr0O67Np6J+TIAiCIOxFmRYjKrUSQBn/EAiCIAgAwKZNm+Dp6al7PnPmTDRo0MBu8ylLlOl1WK0pECNkGSEIgiAM+PLLLxEREWHvaZQJynQ2jUqjAlDGFRlBEATBi6urK1xdXe09jTJBmV6H1ToxQpYRgiCI15127dph3LhxGDduHDw8PODt7Y1p06ZBo2HqN6SlpWHw4MEoV64cnJ2d0a1bNzx69Mjk8fjcNBs2bEDt2rUhlUrh7++PcePGAQCGDx+Onj17csYqFAr4+Phg/fr1xftG30DKthhRk2WEIAjiTeK3336DWCzGxYsXsXjxYixcuBDr1q0DAAwdOhSXL1/G7t27ERkZCY1Gg+7du1udkrpy5UqMHTsWn3zyCW7duoXdu3ejatWqAICRI0fi4MGDiIuL043fu3cvcnNzMXDgwOJ/o28YZdtNA7KMEARBvEkEBQXh119/hUAgQFhYGG7duoVff/0V7dq1w+7du3H27Fm0atUKAPDnn38iKCgI//77L959912Lx547dy4mTZqE8ePH67Y1bdoUANCqVSuEhYXhjz/+wNdffw0A2LhxI959911y9VhBmTYKqNWM6Y4qsBIEQbwZtGjRglP3omXLlnj06BHu3r0LsViM5s2b614rX748wsLCcO/ePYvHTUxMRGxsLDp27GhyzMiRI7Fx40YAQEJCAg4cOIDhw4cX4d2UHcq2GCmIGRGQZYQgCIIwg7bsuTkGDx6Mp0+fIjIyEps3b0ZoaCjatm1bCrN7/SnTYgRgTCIkRQiCIN4MLly4wHl+/vx5VKtWDbVq1YJSqeS8npKSggcPHqBWrVoWj+vm5oaQkBCzqb7ly5dH3759sXHjRmzatAnDhg0r/BspYxRKjCxfvhwhISFwdHRE8+bNcfHiRZNj165di7Zt26JcuXIoV64cwsPDzY4vTTQaNQCyjBAEQbwpREdHY+LEiXjw4AH++usvLF26FOPHj0e1atXQp08fjBo1CmfOnMGNGzfw0UcfITAwEH369LHq2DNnzsSCBQuwZMkSPHr0CFevXsXSpUs5Y0aOHInffvsN9+7dw5AhQ0riLb6R2CxGtm3bhokTJ2LGjBm4evUq6tevjy5duuhaCBty4sQJfPDBBzh+/DgiIyMRFBSEzp07IyYmpsiTLypqnRghCIIg3gQGDx6MvLw8NGvWDGPHjsX48ePxySefAGACShs3boyePXuiZcuW0Gg02L9/PyQSiVXHHjJkCBYtWoQVK1agdu3a6Nmzp1FqcHh4OPz9/dGlSxcEBAQU+/t7UxFotAnYVtK8eXM0bdoUy5YtAwCo1WoEBQXh888/x5QpUyzur1KpUK5cOSxbtgyDBw/mHSOTySCTyXTPMzMzERQUhIyMDLi7u9syXbP8+tcYbJCfRl2ZFFs+uVxsxyUIgnjVyM/PR1RUFEJDQ+Ho6Gjv6ZQI7dq1Q4MGDbBo0SK7zSE7OxuBgYHYuHEj+vfvb7d5lCbmvluZmZnw8PCwuH7bZBmRy+W4cuUKwsPD9QcQChEeHo7IyEirjpGbmwuFQgEvLy+TY+bPnw8PDw/dT1BQkC3TtBo1yE1DEARBFB21Wo3ExETMmTMHnp6e6N27t72n9FphkxhJTk6GSqWCr68vZ7uvry/i4+OtOsbkyZMREBDAETSGTJ06FRkZGbqfFy9e2DJN69FQACtBEARRdKKjo+Hr64stW7Zgw4YNEIvLdBkvmynVT+uHH37A1q1bceLECbNmQqlUCqlUWuLzUVMAK0EQxBvDiRMn7HbukJAQ2Bj1QLCwSYx4e3tDJBIhISGBsz0hIQF+fn5m9/3ll1/www8/4OjRo6hXr57tMy0BNJTaSxAEQRB2xyY3jYODAxo3bszJs1ar1YiIiEDLli1N7vfTTz9hzpw5OHjwIJo0aVL42RYzlNpLEARBEPbHZjfNxIkTMWTIEDRp0gTNmjXDokWLkJOToyvuMnjwYAQGBmL+/PkAgB9//BHTp0/Hli1bEBISoosteRVaM5ObhiAIgiDsj81iZODAgUhKSsL06dMRHx+PBg0a4ODBg7qg1ujoaAiFeoPLypUrIZfLMWDAAM5xZsyYgZkzZxZt9kWG3DQEQRAEYW8KFcA6btw4jBs3jvc1wwCiZ8+eFeYUpYJal01DcoQgCIIg7EWZ7k2joTojBEEQBGF3SIyAxAhBEARRdFJSUuDj4/NKewRCQkJsqlD7/vvvY8GCBSU3oQLKtBghNw1BEARhiEajwfTp0+Hv7w8nJyeEh4cb9aDhY968eejTpw9CQkJKfpKlxHfffYd58+YhIyOjRM9TpsUIyDJCEARBGPDTTz9hyZIlWLVqFS5cuAAXFxd06dIF+fn5JvfJzc3F+vXrMWLEiCKdW6VSQa1WF+kYxUmdOnVQpUoVbN68uUTPU6bFiLZanoC0CEEQZRCNRoNcudIuP7ZUK7148SLatm0LNzc3uLi4oG7durh06VKJfSaLFi3Cd999hz59+qBevXr4/fffERsbi3///dfkfvv374dUKkWLFi0423fv3o1q1arB0dER7du3x2+//QaBQID09HQAwKZNm+Dp6Yndu3ejVq1akEqliI6Ohkwmw5dffonAwEC4uLigefPmRgkiZ86cQdu2beHk5ISgoCB88cUXyMnJ0b2emJiIXr16wcnJCaGhofjzzz85+w8fPhw9e/bkbFMoFPDx8cH69et123r16oWtW7fa8CnaTpkunq/WaAABWUYIgiib5ClUqDX9kF3OfXd2Fzg7WLcEvf/++2jVqhXWrFkDR0dHPH361KhHGpvRo0dbvJPPzs7m3R4VFYX4+HhO/zQPDw80b94ckZGReP/993n3O336NBo3bmx0rAEDBmD8+PEYOXIkrl27hi+//NJo39zcXPz4449Yt24dypcvDx8fH4wbNw53797F1q1bERAQgF27dqFr1664desWqlWrhidPnqBr166YO3cuNmzYgKSkJF2m68aNGwEAQ4cORWxsLI4fPw6JRIIvvvgCiYmJuvOOHDkSb731FuLi4uDv7w8A2Lt3L3JzczFw4EDduGbNmmHevHmQyWQl1qqlTIsRctMQBEG8+iiVSgQHB6Nq1aqQSCQIDQ01O3727Nm8i741aAtz2toQ9vnz5wgICOBsW716NcLCwvDzzz8DAMLCwnD79m3MmzePM06hUGDFihWoX78+AKZe18aNGxEdHa075pdffomDBw9i48aN+P777zF//nx8+OGHmDBhAgCgWrVqWLJkCd5++22sXLkS0dHROHDgAC5evIimTZsCANavX4+aNWvqztuqVSuEhYXhjz/+wNdffw0A2LhxI959911OUdKAgADI5XLEx8ejUqVK1n2QNlKmxQgFsBIEUZZxkohwd3YXu53bWnbu3Il+/frhp59+gqOjI2JiYuDh4WFyvI+PD3x8fIpjmlaTl5dn1AD2wYMHOiGgpVmzZkb7Ojg4cHq23bp1CyqVCtWrV+eMk8lkKF++PADgxo0buHnzJsf1otFooFarERUVhYcPH0IsFnOsNTVq1ICnpyfnmCNHjsSaNWvw9ddfIyEhAQcOHMCxY8c4Y5ycnAAwFpySokyLEX2jPBIjBEGUPQQCgdWuEnsydepUNG3aFFOmTIGXlxfc3NzMji+Km0bb9DUhIUHnutA+b9CggcnjeXt7Iy0tzew5TeHk5AQBK3gxOzsbIpEIV65cgUjEFW1ai0V2djY+/fRTfPHFF0bHCw4OxsOHD6069+DBgzFlyhRERkbi3LlzCA0NRdu2bTljUlNTAQAVKlSw6X3Zwqv/LSxRyE1DEATxKpOcnIyjR4/i+vXrOjeGJYripgkNDYWfnx8iIiJ04iMzMxMXLlzAZ599ZnK/hg0bGgmgsLAw7N+/n7PNmsDbhg0bQqVSITEx0UgYaGnUqBHu3r2LqlWr8r5eo0YNKJVKXLlyRWedefDggS5wVkv58uXRt29fbNy4EZGRkbo+c2xu376NihUrwtvb2+LcC0uZFiNqrWWE0mkIgiBeSby9vREUFITp06dj+vTp8Pb2RlRUFORyOTp37sy7T1HcNAKBABMmTMDcuXNRrVo1hIaGYtq0aQgICEDfvn1N7telSxdMnToVaWlpKFeuHADg008/xcKFCzF58mSMGDEC169fx6ZNm3TnMUX16tXx4YcfYvDgwViwYAEaNmyIpKQkREREoF69eujRowcmT56MFi1aYNy4cRg5ciRcXFxw9+5dHDlyBMuWLUNYWBi6du2KTz/9FCtXroRYLMaECRN0Lhc2I0eORM+ePaFSqTBkyBCj10+fPm3ysy4uKLUXZBkhCIJ4lTlw4ADUajW6dOmC6tWrY9SoUUhISCix83399df4/PPP8cknn6Bp06bIzs7GwYMHjWJC2NStWxeNGjXC9u3bddtCQ0OxY8cO7Ny5E/Xq1cPKlSvx7bffAoDFrJSNGzdi8ODBmDRpEsLCwtC3b19cunQJwcHBAIB69erh5MmTePjwIdq2bYuGDRti+vTpnCDajRs3IiAgAG+//Tb69++PTz75hFekhYeHw9/fH126dDEKws3Pz8e///6LUaNGWf7gioBAY0uyt53IzMyEh4cHMjIy4O7uXmzHnby+B/aLo9FB4YfFI48U23EJgiBeNfLz8xEVFYXQ0FCziypRePbt24evvvoKt2/f5nSvZzNv3jysWrUKL168KOXZmSY7OxuBgYHYuHEj+vfvz3lt5cqV2LVrFw4fPmxyf3PfLWvX7zLtpqEAVoIgCKK46NGjBx49eoSYmBgEBQUBAFasWIGmTZuifPnyOHv2LH7++WeTXe9LG7VajeTkZCxYsACenp7o3bu30RiJRIKlS5eW+FzKthjRUMwIQRAEUXxo635oefToEebOnYvU1FQEBwdj0qRJmDp1qn0mZ0B0dDRCQ0NRsWJFbNq0CWKxsSQYOXJkqcylbIsRrWVEQ2KEIAiCKH5+/fVX/Prrr/aeBi8hISE2leUvScp2AKsum6ZMfwwEQRAEYVfK9CqsjxkhCIIgCMJelG0xoiHLCEEQBEHYmzK+ClM2DUEQBEHYmzItRrQVWIUkRgiCIAjCbpRpMaKNGQGl9hIEQRCE3SAxAnLTEARBEIQ9KdtiRKN105Tpj4EgCIJgodFoMH36dPj7+8PJyQnh4eF49OiRxf2WL1+OkJAQODo6onnz5rh48SLn9TVr1qBdu3Zwd3eHQCAw6qBblinjqzBVYCUIgiC4/PTTT1iyZAlWrVqFCxcuwMXFBV3+3969B0V1nn8A/y6XZZfA7gorLBgWN5WJJhK8oAQ0ph0YkTgpYMcWShI0TvxhZSI1UfGGjTcsmWRMrIkxHUkzmpjaQdJm1JagRJ3gKkZUYkO8YKHGhVCDCyJy2ff3R8KJG0G5LHvA/X5mdpRznnP2OY8r55lzzvtufDxaWlq63eajjz7C4sWLsWbNGnzxxReIiIhAfHw86urqpJjm5mbMmDEDK1ascMZhDCku3YzYOOkZEbkyIYDWG/K8ejHz5/Hjx/HEE0/A19cXDzzwAMLDw3HixIkBKonA5s2bsWrVKiQmJuKxxx7D+++/j2+++QaFhYXdbvf666/jhRdewNy5c/HII49g27Zt8Pb2xo4dO6SYrKwsZGdn4/HHHx+Q3IcyTgcPPjNCRC6qrRnYGHzvuIGw4htA+UCPQlNSUhATE4Pt27dDpVLh0qVLCAwM7DY+IyMDO3fuvOs+m5qaulxeVVUFi8WCuLg4aZlWq0VUVBRKS0uRkpJyxzatra04efKk3XfOuLm5IS4uDqWlpfc6PAKbEQBsRoiIBrP29nYYjUaMGjUKnp6eMJlMd41fu3YtXn755T69l8ViAYA7mp3AwEBp3U/V19ejo6Ojy22++uqrPuXhatiMgLdpiMhFeXp/f4VCrvfuoYKCAiQnJyMvLw8qlQpXrlyBVqvtNj4gIAABAQGOyJKcxKWbkU4cTUNELkmh6PGtEjktX74ckyZNQnZ2Nvz8/ODr63vX+P7cpjEYDACA2tpaBAUFSctra2sxbty4LrfR6/Vwd3dHbW2t3fLa2lppf3R3Lt2M2DiahohoUKuvr8enn36K8vJyRERE9Gib/tymMZlMMBgMKC4ulpoPq9UKs9mMBQsWdLmNUqnExIkTUVxcjKSkJACAzWZDcXExMjMz+5SHq3HpZqTzaW4Fr4wQEQ1Ker0eISEhyMnJQU5ODvR6PaqqqtDa2orp06d3uU1/btMoFApkZWVh/fr1CAsLg8lkwurVqxEcHCw1GgAQGxuL5ORkqdlYvHgx0tPTERkZicmTJ2Pz5s24ceMG5s6dK21jsVhgsVhw4cIFAMDZs2fh6+sLo9EIPz+/PuV7v3DpZsQmXRDhlREiosFq//79yM7ORnx8PBobG2E0GpGTkzNg77d06VLcuHED8+fPR0NDA6ZOnYoDBw5ApVJJMRcvXkR9fb30829+8xt8++23yMnJgcViwbhx43DgwAG7h1q3bduGV155Rfp52rRpAID8/HzMmTNnwI5nKFAI0YvB3j/YunUrXn31VVgsFkRERGDLli2YPHlyt/F79uzB6tWrcfnyZYSFheGPf/wjnnrqqR6/n9VqhVarxfXr16HRaHqbbreef+dxnFDdQKr7RKx45j2H7ZeIaLBpaWlBVVUVTCaT3UmVqL/u9tnq6fm71/cnejLL3O0+//xzpKamYt68eTh16hSSkpKQlJSEioqK3r61wwnFD9PBczQNERGRbHp9Fu7JLHO3e+ONNzBjxgwsWbIEY8aMwbp16zBhwgT86U9/6nfy/dZ5TYjNCBERkWx6dRbunGXu9pnp7jXLXGlpqV08AMTHx991Vrpbt27BarXavQaCdGWED7ASERHJpldn4bvNMtfdzHQWi6VX8QCQm5sLrVYrvUJCQnqTZo91Pi7Dob1ERETyGZSXBJYvX47r169Lr5qamgF5n87RNJyBlYiISD69Gtrbl1nmDAZDr2el8/LygpeXV29S65POKyN8gJWIiEg+vToL3z7LXKfOWeaio6O73CY6OtouHgCKioq6jXcuTnpGREQkt15PenavWeaee+45jBgxArm5uQCARYsW4cknn8Rrr72GmTNnYvfu3SgrK8P27dsdeyR9IA2m4TMjREREsul1M3KvWeaqq6vh5vbjlYaYmBh88MEHWLVqFVasWIGwsDAUFhZi7NixjjuKPuJoGiIiIvn1aTr4zMzMbr/8p6Sk5I5ls2fPxuzZs/vyVgPqx2lG2IwQERHJxaXPwjY+M0JERD8hhEBOTg6CgoKgVqsRFxeH8+fP33Wbw4cP4+mnn0ZwcDAUCgUKCwudk+x9gmdhcGgvERH9KC8vD2+++Sa2bdsGs9mMBx54APHx8Whpael2mxs3biAiIgJbt251Yqb3D5f+1l4BDu0lItclhMDN9puyvLfaQ93jwQPHjx/HSy+9hPLycthsNjz00EPYsWMHJk2a5PC8hBDYvHkzVq1ahcTERADA+++/j8DAQBQWFiIlJaXL7RISEpCQkODwfFyFizcj32MzQkSu6Gb7TUR9ECXLe5t/a4a3p3ePYlNSUhATE4Pt27dDpVLh0qVLd8zsfbuMjAzs3LnzrvtsamrqcnlVVRUsFovd15hotVpERUWhtLS022aE+sfFm5HO6eDZjBARDVbt7e0wGo0YNWoUPD09YTKZ7hq/du1avPzyy316r86vKunt15hQ/7h0M2L74U83cJ4RInI9ag81zL81y/bePVVQUIDk5GTk5eVBpVLhypUr0Gq13cYHBAQgICDAEWmSk7h0MxLZ4o5HW63w1+vkToWIyOkUCkWPb5XIafny5Zg0aRKys7Ph5+cHX1/fu8b35zZN51eV1NbWIigoSFpeW1uLcePG9S5x6jGXbkbim4Zh5K06XB4zMN8KTERE/VNfX49PP/0U5eXliIiI6NE2/blNYzKZYDAYUFxcLDUfVqsVZrMZCxYs6NM+6d5cuhnJ81+P8poGvBU8Qe5UiIioC3q9HiEhIcjJyUFOTg70ej2qqqrQ2tqK6dOnd7lNf27TKBQKZGVlYf369QgLC4PJZMLq1asRHByMpKQkKS42NhbJycnSBKBNTU24cOGCtL6qqgrl5eXw8/OD0WjsUy6uxKWbkY/+bzB8WR8REd3N/v37kZ2djfj4eDQ2NsJoNCInJ2fA3m/p0qW4ceMG5s+fj4aGBkydOhUHDhyASqWSYi5evIj6+nrp57KyMvziF7+Qfl68eDEAID09He+9996A5Xq/UAghxL3D5GW1WqHVanH9+nVoNBq50yEiGnJaWlpQVVUFk8lkd1Il6q+7fbZ6ev7mmFYiIiKSFZsRIiIikhWbESIiIpIVmxEiIiKSFZsRIiIXMgTGLNAQ44jPFJsRIiIX4OnpCQBobm6WORO633R+pjo/Y33h0vOMEBG5Cnd3d+h0OtTV1QEAvL29oVDwe7mo74QQaG5uRl1dHXQ6Hdzd3fu8LzYjREQuovN7VzobEiJH0Ol00merr9iMEBG5CIVCgaCgIAQEBKCtrU3udOg+4Onp2a8rIp3YjBARuRh3d3eHnECIHIUPsBIREZGs2IwQERGRrNiMEBERkayGxDMjnROqWK1WmTMhIiKinuo8b99rYrQh0Yw0NjYCAEJCQmTOhIiIiHqrsbERWq222/UKMQTmBrbZbPjmm2/g6+vr0El6rFYrQkJCUFNTA41G47D90p1Ya+dgnZ2DdXYO1tl5BqrWQgg0NjYiODgYbm7dPxkyJK6MuLm54cEHHxyw/Ws0Gn7QnYS1dg7W2TlYZ+dgnZ1nIGp9tysinfgAKxEREcmKzQgRERHJyqWbES8vL6xZswZeXl5yp3LfY62dg3V2DtbZOVhn55G71kPiAVYiIiK6f7n0lREiIiKSH5sRIiIikhWbESIiIpIVmxEiIiKSlUs3I1u3bsXIkSOhUqkQFRWF48ePy53SkJGbm4tJkybB19cXAQEBSEpKQmVlpV1MS0sLFi5cCH9/f/j4+OBXv/oVamtr7WKqq6sxc+ZMeHt7IyAgAEuWLEF7e7szD2VI2bRpExQKBbKysqRlrLPjXLlyBc888wz8/f2hVqsRHh6OsrIyab0QAjk5OQgKCoJarUZcXBzOnz9vt49r164hLS0NGo0GOp0O8+bNQ1NTk7MPZdDq6OjA6tWrYTKZoFar8bOf/Qzr1q2z++4S1rlvDh8+jKeffhrBwcFQKBQoLCy0W++oup45cwZPPPEEVCoVQkJCkJeX1//khYvavXu3UCqVYseOHeLLL78UL7zwgtDpdKK2tlbu1IaE+Ph4kZ+fLyoqKkR5ebl46qmnhNFoFE1NTVJMRkaGCAkJEcXFxaKsrEw8/vjjIiYmRlrf3t4uxo4dK+Li4sSpU6fEvn37hF6vF8uXL5fjkAa948ePi5EjR4rHHntMLFq0SFrOOjvGtWvXRGhoqJgzZ44wm83i0qVL4p///Ke4cOGCFLNp0yah1WpFYWGhOH36tPjlL38pTCaTuHnzphQzY8YMERERIY4dOyaOHDkiRo0aJVJTU+U4pEFpw4YNwt/fX3zyySeiqqpK7NmzR/j4+Ig33nhDimGd+2bfvn1i5cqVoqCgQAAQe/futVvviLpev35dBAYGirS0NFFRUSE+/PBDoVarxTvvvNOv3F22GZk8ebJYuHCh9HNHR4cIDg4Wubm5MmY1dNXV1QkA4rPPPhNCCNHQ0CA8PT3Fnj17pJh///vfAoAoLS0VQnz/H8fNzU1YLBYp5u233xYajUbcunXLuQcwyDU2NoqwsDBRVFQknnzySakZYZ0dZ9myZWLq1KndrrfZbMJgMIhXX31VWtbQ0CC8vLzEhx9+KIQQ4ty5cwKAOHHihBSzf/9+oVAoxJUrVwYu+SFk5syZ4vnnn7dbNmvWLJGWliaEYJ0d5afNiKPq+tZbb4lhw4bZ/e5YtmyZePjhh/uVr0vepmltbcXJkycRFxcnLXNzc0NcXBxKS0tlzGzoun79OgDAz88PAHDy5Em0tbXZ1Xj06NEwGo1SjUtLSxEeHo7AwEApJj4+HlarFV9++aUTsx/8Fi5ciJkzZ9rVE2CdHenvf/87IiMjMXv2bAQEBGD8+PF49913pfVVVVWwWCx2tdZqtYiKirKrtU6nQ2RkpBQTFxcHNzc3mM1m5x3MIBYTE4Pi4mJ8/fXXAIDTp0/j6NGjSEhIAMA6DxRH1bW0tBTTpk2DUqmUYuLj41FZWYnvvvuuz/kNiS/Kc7T6+np0dHTY/XIGgMDAQHz11VcyZTV02Ww2ZGVlYcqUKRg7diwAwGKxQKlUQqfT2cUGBgbCYrFIMV39G3Suo+/t3r0bX3zxBU6cOHHHOtbZcS5duoS3334bixcvxooVK3DixAm8+OKLUCqVSE9Pl2rVVS1vr3VAQIDdeg8PD/j5+bHWP8jOzobVasXo0aPh7u6Ojo4ObNiwAWlpaQDAOg8QR9XVYrHAZDLdsY/OdcOGDetTfi7ZjJBjLVy4EBUVFTh69Kjcqdx3ampqsGjRIhQVFUGlUsmdzn3NZrMhMjISGzduBACMHz8eFRUV2LZtG9LT02XO7v7x17/+Fbt27cIHH3yARx99FOXl5cjKykJwcDDr7MJc8jaNXq+Hu7v7HSMOamtrYTAYZMpqaMrMzMQnn3yCQ4cO4cEHH5SWGwwGtLa2oqGhwS7+9hobDIYu/w0619H3t2Hq6uowYcIEeHh4wMPDA5999hnefPNNeHh4IDAwkHV2kKCgIDzyyCN2y8aMGYPq6moAP9bqbr83DAYD6urq7Na3t7fj2rVrrPUPlixZguzsbKSkpCA8PBzPPvssfv/73yM3NxcA6zxQHFXXgfp94pLNiFKpxMSJE1FcXCwts9lsKC4uRnR0tIyZDR1CCGRmZmLv3r04ePDgHZftJk6cCE9PT7saV1ZWorq6WqpxdHQ0zp49a/fhLyoqgkajueOk4KpiY2Nx9uxZlJeXS6/IyEikpaVJf2edHWPKlCl3DE//+uuvERoaCgAwmUwwGAx2tbZarTCbzXa1bmhowMmTJ6WYgwcPwmazISoqyglHMfg1NzfDzc3+1OPu7g6bzQaAdR4ojqprdHQ0Dh8+jLa2NimmqKgIDz/8cJ9v0QBw7aG9Xl5e4r333hPnzp0T8+fPFzqdzm7EAXVvwYIFQqvVipKSEnH16lXp1dzcLMVkZGQIo9EoDh48KMrKykR0dLSIjo6W1ncOOZ0+fbooLy8XBw4cEMOHD+eQ03u4fTSNEKyzoxw/flx4eHiIDRs2iPPnz4tdu3YJb29vsXPnTilm06ZNQqfTiY8//licOXNGJCYmdjk0cvz48cJsNoujR4+KsLAwlx9yerv09HQxYsQIaWhvQUGB0Ov1YunSpVIM69w3jY2N4tSpU+LUqVMCgHj99dfFqVOnxH/+8x8hhGPq2tDQIAIDA8Wzzz4rKioqxO7du4W3tzeH9vbHli1bhNFoFEqlUkyePFkcO3ZM7pSGDABdvvLz86WYmzdvit/97ndi2LBhwtvbWyQnJ4urV6/a7efy5csiISFBqNVqodfrxUsvvSTa2tqcfDRDy0+bEdbZcf7xj3+IsWPHCi8vLzF69Gixfft2u/U2m02sXr1aBAYGCi8vLxEbGysqKyvtYv73v/+J1NRU4ePjIzQajZg7d65obGx05mEMalarVSxatEgYjUahUqnEQw89JFauXGk3VJR17ptDhw51+Xs5PT1dCOG4up4+fVpMnTpVeHl5iREjRohNmzb1O3eFELdNe0dERETkZC75zAgRERENHmxGiIiISFZsRoiIiEhWbEaIiIhIVmxGiIiISFZsRoiIiEhWbEaIiIhIVmxGiIiISFZsRoiIiEhWbEaIaMDNmTMHSUlJcqdBRIMUmxEiIiKSFZsRInKYv/3tbwgPD4darYa/vz/i4uKwZMkS/OUvf8HHH38MhUIBhUKBkpISAEBNTQ1+/etfQ6fTwc/PD4mJibh8+bK0v84rKq+88gqGDx8OjUaDjIwMtLa2ynOARDQgPOROgIjuD1evXkVqairy8vKQnJyMxsZGHDlyBM899xyqq6thtVqRn58PAPDz80NbWxvi4+MRHR2NI0eOwMPDA+vXr8eMGTNw5swZKJVKAEBxcTFUKhVKSkpw+fJlzJ07F/7+/tiwYYOch0tEDsRmhIgc4urVq2hvb8esWbMQGhoKAAgPDwcAqNVq3Lp1CwaDQYrfuXMnbDYb/vznP0OhUAAA8vPzodPpUFJSgunTpwMAlEolduzYAW9vbzz66KNYu3YtlixZgnXr1sHNjRd3ie4H/J9MRA4RERGB2NhYhIeHY/bs2Xj33Xfx3XffdRt/+vRpXLhwAb6+vvDx8YGPjw/8/PzQ0tKCixcv2u3X29tb+jk6OhpNTU2oqakZ0OMhIufhlREicgh3d3cUFRXh888/x7/+9S9s2bIFK1euhNls7jK+qakJEydOxK5du+5YN3z48IFOl4gGETYjROQwCoUCU6ZMwZQpU5CTk4PQ0FDs3bsXSqUSHR0ddrETJkzARx99hICAAGg0mm73efr0ady8eRNqtRoAcOzYMfj4+CAkJGRAj4WInIe3aYjIIcxmMzZu3IiysjJUV1ejoKAA3377LcaMGYORI0fizJkzqKysRH19Pdra2pCWlga9Xo/ExEQcOXIEVVVVKCkpwYsvvoj//ve/0n5bW1sxb948nDt3Dvv27cOaNWuQmZnJ50WI7iO8MkJEDqHRaHD48GFs3rwZVqsVoaGheO2115CQkIDIyEiUlJQgMjISTU1NOHToEH7+85/j8OHDWLZsGWbNmoXGxkaMGDECsbGxdldKYmNjERYWhmnTpuHWrVtITU3FH/7wB/kOlIgcTiGEEHInQUTUlTlz5qChoQGFhYVyp0JEA4jXOYmIiEhWbEaIiIhIVrxNQ0RERLLilREiIiKSFZsRIiIikhWbESIiIpIVmxEiIiKSFZsRIiIikhWbESIiIpIVmxEiIiKSFZsRIiIiktX/A37xEGem3/IfAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "policy_names = {\n",
    "    0: 'ε = 0.1',\n",
    "    1: 'ε = 0.01',\n",
    "    2: 'ε = 0 (greedy)'\n",
    "}\n",
    "\n",
    "(\n",
    "    trace_df\n",
    "    .assign(policy=trace_df.policy_idx.map(policy_names))\n",
    "    .groupby(['step', 'policy'])\n",
    "    ['reward'].mean()\n",
    "    .unstack()\n",
    "    .plot()\n",
    ")\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Controlling the evaluation loop"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `bandit.evaluate` function is useful for benchmarking. But in practice, you'll want to have control over your bandit policy. Indeed you'll want the freedom to pull arms (with the `pull` method) and update the policy (with the `update` method) at your discretion.\n",
    "\n",
    "As an example, the following is a possible reimplementation of the `bandit.evaluate` function. Here we'll be measuring the rate at which each policy selects the optimal arm.\n",
    "\n",
    "Note how the `pull` and `update` methods are used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:48:00.839669Z",
     "iopub.status.busy": "2023-12-04T17:48:00.837348Z",
     "iopub.status.idle": "2023-12-04T17:48:29.796813Z",
     "shell.execute_reply": "2023-12-04T17:48:29.796482Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  0%|                                                                                                                                                                   | 0/6000000 [00:00<?, ?it/s]/Users/max/Library/Caches/pypoetry/virtualenvs/river--dXL33ck-py3.11/lib/python3.11/site-packages/gym/utils/passive_env_checker.py:233: DeprecationWarning: `np.bool8` is a deprecated alias for `np.bool_`.  (Deprecated NumPy 1.24)\n",
      "  if not isinstance(terminated, (bool, np.bool8)):\n",
      "100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 6000000/6000000 [00:26<00:00, 228987.26it/s]\n"
     ]
    }
   ],
   "source": [
    "import copy\n",
    "\n",
    "policies=[\n",
    "    bandit.EpsilonGreedy(epsilon=0.1),\n",
    "    bandit.EpsilonGreedy(epsilon=0.01),\n",
    "    bandit.EpsilonGreedy(epsilon=0),\n",
    "]\n",
    "\n",
    "env = gym.make(\n",
    "    'river_bandits/KArmedTestbed-v0',\n",
    "    max_episode_steps=1000\n",
    ")\n",
    "n_episodes = 2000\n",
    "\n",
    "trace = []\n",
    "\n",
    "with tqdm(total=len(policies) * n_episodes * env._max_episode_steps, position=0) as progress:\n",
    "    for policy in policies:\n",
    "        for episode in range(n_episodes):\n",
    "            episode_policy = policy.clone()\n",
    "            episode_env = copy.deepcopy(env)\n",
    "            episode_env.reset()\n",
    "            step = 0\n",
    "            while True:\n",
    "                action = episode_policy.pull(range(episode_env.action_space.n))\n",
    "                observation, reward, terminated, truncated, info = episode_env.step(action)\n",
    "                best_action = observation\n",
    "                episode_policy.update(action, reward)\n",
    "\n",
    "                trace.append({\n",
    "                    \"episode\": episode,\n",
    "                    \"step\": step,\n",
    "                    \"policy\": f\"ε = {policy.epsilon}\",\n",
    "                    \"is_action_optimal\": action == best_action\n",
    "                })\n",
    "                step += 1\n",
    "                progress.update()\n",
    "\n",
    "                if terminated or truncated:\n",
    "                    break\n",
    "\n",
    "trace_df = pd.DataFrame(trace)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:48:29.798595Z",
     "iopub.status.busy": "2023-12-04T17:48:29.798478Z",
     "iopub.status.idle": "2023-12-04T17:48:30.254020Z",
     "shell.execute_reply": "2023-12-04T17:48:30.253664Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Axes: xlabel='step'>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAiMAAAGwCAYAAAB7MGXBAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy81sbWrAAAACXBIWXMAAA9hAAAPYQGoP6dpAAB3bklEQVR4nO3dd3gU5drH8e+mJ6QBIQklQCjSi7QICqJEI6KCFZQjiIoVBREVLKBY8FUPBwuKegQLFiyADfFAEAUJoCC919CSECC97877x5ANSwpJSLIJ+X2uay9nnnlm9t4JZu888xSLYRgGIiIiIk7i4uwAREREpHZTMiIiIiJOpWREREREnErJiIiIiDiVkhERERFxKiUjIiIi4lRKRkRERMSp3JwdQGnYbDaOHj2Kn58fFovF2eGIiIhIKRiGQWpqKo0aNcLFpfj2jxqRjBw9epSwsDBnhyEiIiLlcOjQIZo0aVLs8RqRjPj5+QHmh/H393dyNCIiIlIaKSkphIWF2b/Hi1MjkpH8RzP+/v5KRkRERGqYc3WxUAdWERERcSolIyIiIuJUSkZERETEqZSMiIiIiFMpGRERERGnUjIiIiIiTqVkRERERJxKyYiIiIg4lZIRERERcSolIyIiIuJUSkZERETEqZSMiIiIiFMpGREREanBcqw5WG1WZ4dxXpSMiIiI1FBZeVlc9e1V3LHoDmeHcl7cnB2AiIiImOLS4/D38MfH3adU9bed2MbJrJOczDqJzbDhYil7G8MX278gx5pDVPMoGvo2LPP5FUHJiIiIyGlWmxVXF1envPextGNc/d3VBPsEE31rdKnOsVgs9u2svKxSJzEAubZcnl/1PD/s/QGArsFdnZaM6DGNiIgIkJiZSP+v+/NizIuVcv0NCRtIyEgoVJ5ny2PV0VX8fvh3ABIyEjAMo1TXzLXm2rcz8zI5mnaUvUl7S3Xu8kPL7YkIQD2veqU6rzKUKxmZOXMmzZs3x8vLi4iICNauXVti/RkzZtCmTRu8vb0JCwvjscceIysrq1wBi4iIVIYvtn9BUnYSX+/6+px1DyQfYNhPw1h6cCkAf8f9zayNs7DarKTlpJGV5/gdtzVxK3f+cicDvxtY6Fpf7/ya+5fcz8trXraXpeSknDOGPFse9/zvHvt+Wm4aUd9FMeT7ISzev5g5W+ZwKPVQofOy8rJIzk7Gajh2eq3vXf+c71lZyvyYZt68eYwfP55Zs2YRERHBjBkziIqKYufOnQQHBxeq/8UXXzBx4kRmz55Nnz592LVrF3fddRcWi4Xp06dXyIcQERE5XznWnFLXffWvV9l6YiuPLX+MX2/+lVG/jgLMRx8fbPqAel71+H3o7/b6McdizPewFX6PhXsWFipLyEggwDOgxBj+jv/bYX/T8U327Sf+eAKA6eumc0PLG7j1olsJ8g6isW9jRi4eyf7k/dx20W0O5/u4lf4RT0Urc8vI9OnTGT16NKNGjaJ9+/bMmjULHx8fZs+eXWT9VatWcemll3LHHXfQvHlzrr76am6//fYSW1Oys7NJSUlxeImIyIUhLj2Oj7d8TGpOqr0sz5bHMyuf4eudjq0Seba8Ml17WewylsUuA8wWh2dXPlvqa+Tacs9ZJ8+Wh2EYpGYXxB71XZR9+4NNHwBwMuukwyMUV0tBP5SsvCysNis2w8b83fOxGbZC7xOfEc/h1MMcTj1sL/vv5v/y6tpX7Y9wNh/f7HDOnK1zioz5h70/mK0y8wfy/qb32XZiG5l5mXyy7ROHemf2P6lqZUpGcnJyWLduHZGRkQUXcHEhMjKSmJiYIs/p06cP69atsycf+/btY9GiRVx77bXFvs+0adMICAiwv8LCwsoSpoiIVJH03PQyn/Pg0gf597p/8/pfr9vLlsUu44e9P/Di6oL+GicyT3DF11fw3J/PlXg9wzBIz00nMTORsb+NZexvY8m2ZvPi6hf5fu/3LI1daq+7L2kf9/x6D3/F/WWPP//L/cxWi6L6bGTlZXH9guu5f8n9peoomp6bTq41l5VHVpKcnWwv33FyB9ctuI4un3Zhyqop7Dy1s9C56+PXM3D+QAYtGESuNRerzcqb69/k8+2fs/3kdtJy0jiVfcrhnN2ndp8zppkbZp6zjjOUKRlJTEzEarUSEhLiUB4SEkJcXFyR59xxxx1MnTqVyy67DHd3d1q2bEn//v15+umni32fSZMmkZycbH8dOlT4mZeIiDjXJ1s/4ZIvLrH3myitPUl7APj1wK/2spNZJ+3b+f0lvtv9HUnZSYUeY3yy9ROGLxpu/4J/ec3LXPbVZQ71UrILWtTj0gq+n55a8RRr49Zy9693szdpL5d9eZm9r8aZLRlFPU75J+EfDqcdJuZYDKuPrT7n57xu4XW8uvZVHlz6IB9t+chefucvd3I47XAJZ8KHmz8EwGbYiM+I59td39qPDf1pKL2/7M1n2z47ZwylNXOAc5OUSh9Ns3z5cl555RXeffdd1q9fz/z58/n555958cXieyt7enri7+/v8BIRuRCtOrqKgd8NZO2xkgcCVEdv/P0GAE+vNP+43JCwgTXH1jjUKe2okFNZBX/lH0o9xO+Hfuftf962l932421k5Gbw64FfeePvN9h0fBOj/zeaa767hnk755Fny+PN9W/a67+/6X37dnpeQevN0bSjBXU2vk+ekce8nfOIPhjN93u/tx/7bNtn/Lj3R1YfW82B5APsS9rH1hNbS/VZ8iVnJ5eqM+y5LNizgJfWvHTe1ylOn0Z96NekX6VdvzTK1IE1KCgIV1dX4uPjHcrj4+MJDQ0t8pznnnuOO++8k3vvvReATp06kZ6ezn333cczzzyDi4tGF4tI7XX/kvsBGL1kNBtHbDzv6+XacnF3cT+vayzev5jv937Poxc/Srv67c5Z32bYSMlJ4c5f7gTg96G/E3M0hokrJtLYtzELBy/Ey80LwGHa8jP7KBxJO2LfPpp2lE+2OvZn2H5yO5NWTGLZoWUOZcWZt3OefTs2JZYbv7+RTkGdHPpu/HLgF/v2uOXjHM4/M7FxthWHV5T5nL6N+3JT65v4Ztc3rDq6qsS6Z4/8cYYyZQIeHh50796d6OiCyVhsNhvR0dH07t27yHMyMjIKJRyuruY/htJmzCIiF7qiOjGW1YLdC7jk80v44/Af5xXHE388wcojKxkTPYaM3Aze3/g+Kw6v4K31b5GYmUhmXqbD72+rYWXl4ZX2/T2n9jBxxUTATDK+3PElSw4u4cGlD9L1s672ehm5GaTmpJKRm8GJrBMO5UWttXJmIlIWi/YvYk/SHhbsWYCN87/PRWnm36xCrzcwfCC9G5rfq0UlXd8P+b5QWb4PrvqAdyPfJbJZJO9FvlfoeGPfxnRu0Nm+X5ZRRJWlzEN7x48fz8iRI+nRowe9evVixowZpKenM2qUOaxpxIgRNG7cmGnTpgFw/fXXM336dC6++GIiIiLYs2cPzz33HNdff709KRERqSne3/g+q46uYtZVs/B2866y9919ajfzds7j/s7308CnQZF1Jq+aDMDEFRNZfttyUnNSC80dkZaThg0b/h4Fj7+3ndjGS6tfwsvNixtb3WgvT8hM4IqvryAjL8Ne9u2ub8myZnFT65vsZTbD5tCHIr9PSL7p64qexsHAoM+XfQqV/xX3F1tObCnynPN1ZkfSivTJNZ9gsVi4fN7lJdabOWAmD0c/XGKdi+pexGv9XuOVNa/YhwSfKdg7mFCfgqcRY7qO4d5O97L95HZ2ndrFJQ0vsR8ranr4+t71+WzgZ3T5tAsALQJblBhPVShzMjJ06FCOHz/O5MmTiYuLo2vXrixevNjeqTU2NtahJeTZZ5/FYrHw7LPPcuTIERo0aMD111/Pyy+/XNxbiIhUW+9seAeARfsWcfNFNxdZ51TWKV7/63VubH0jPUN7Vsj73vSD+eWfmZfJy5e9jNVmZW/yXloFtir0hZOak0r3ud0B+Pq6rwmpE0I9r3pYbVYGLxyM1bDyv1v+h4erBznWHIb+NNR+bv4ok3xnJiKAfQTH59s/t5fZDBsL9iyw709bO+28PuuZfTdqCn9Pf9xd3HnnyncYs2xMsfX6Nu5bqOyVy15hd9Ju5mwxh+bmt5INaDqAL3d8Waj+R1EfOYzm6d2oN64urnQM6kjHoI6F6ndt0JUNxzfY95/q+RQuFhe+uPYL5u+ZzyMXP1Lqz1lZyrU2zZgxYxgzpuibvXz5csc3cHNjypQpTJkypTxvJSJSbZz5KKW4OSni0uO46turAPhx349sHlkwF4TNsGE1rMX26diauJWdp3ZyY6sbsVgsLN6/mMUHFjOi/Qh7ndiUWADe/udtPtryERN6TGBkh5HFxnzbT+bEVn0a9eGejveQkGlOR34o9RAtA1syd/vc0nx0p5nYayKvrn3VoaxzUGde6fsKL8S8UCh5Ol9uFjfyDHNekkcufsShEy1Avyb9HB6DfTnoS9xc3Ow/08vDLueBLg8wa+Ms+/Ue6PIAAZ4BBPsEY7FYiAiNYE2c2dHX1eLK9S2vB7AnI/mPwHqF9mJQi0H8vO9n2tVrx/tXvU+gZ6C9r82M/jPYn7KfTkGdSvxMr/V7jbnb53JHuzvwcfOhrlddADo16ESnBiWfW1UsRg3ouJGSkkJAQADJyckaWSMiTnMq6xT95pmjDp7v/bxDy8gv+3/haNpRZqyf4XDOmcnI3b/ezV9xf3Fz65t5vs/zAHT6xPwycLW44uHqQWZeJo93f5y7Ot5lP3amG1reQBO/Jry74V2H8qFthjp02ixK95DurItfB5iPC/o27kvnTzuXeE5FWjt8Lb0+71Wqui0CWvDOle8Q5h/G8YzjXPnNlfZjXw76ko5BHR0Sv2b+zTiYcrDY610RdgW/HfrNoczfw58wvzA8XD34J+EfAJr4NrEPu/3nzn/4YNMHvLexoN/FjCtmEJsSy9q4tcV28DUMg43HNxJaJ9RMQLA4dNZNzEzku13f0a5+Oy6qexGhdcxHLvk/7/CAcH4YUrBmzM6TO6nvXZ8g76BS3bvqpLTf31q1V0TkDM+vep4TmSd488o3Cz3+OJFZ0MkyMy+TTcc38fO+n7mn0z08+ceTJV43z5Zn/yv+u93fMaHHBHw9fO3HXS2uZOZlAvDvdf8u9hHQwZSDDoub5TtXIgLYExHgnP0Wztf9ne93GF57Q8sbCvWxiWwa6TAh2Zke7fYoYf7mhJcNfBrwfuT73L/UHHlUx70OAKF1QpnefzoBHgHM2jTLnow83PVhdp/azbLYZUyKmMTauLXc1/k+h2RkwQ0LaFW3FWC2WN33v/twc3EjJSfFnoy4ubiRbc12iMsFF0Z1HMWojqOK/ewWi4WuwV2LPR7kHcT9Xe4v9vjZbQRt6rUptu6FQsmIiFwQ8n+BGxhFdto7s15x017n2fL4bvd3gPnlfnvb2x2ufeaIj9TcVKasmsKepD2FpjA/U441h/3J+/l468cO5aeyTnEs/Zh9/+yY/jz6Z5HX23j8/If/lpW3mzdLblnCS6tfYvGBxUXWcXNxY1rfaTzxu7kmylXNriLHlsOcLXPo36Q/L19WuJ/gtL7TeCb3Ga74+opCx8IDwh32z1ynxc/Dz759VTOzZeTMFqkHujxAtjWb1JxUgryDuK2N4xosXq5eDp02XSwu/DfqvwDcuehOh7phfo4zgBfXebgiWLBgYBTZ7+NCp2RERGoEwzD4Ztc3dAjqQF3PuuTZ8kjLTWPNsTXc0e4ORi0exebEzdRxr8PsqNm0r9++0DWWHFzCsyuf5dW+r3JFU8cvwKSsJB5ZVtCR75U1r3BVs6uo71WfuxbfRbY1m+HthtuPn8w8aR81kt/HoChR30WRmJlYqPzf6/5NdGzBNAln/wWe/6VeVi4WF9wsbkXOIFoWVzW7iiUHlwAQ6BlIgGcAr/V7jWcveZbLvrrMoe6aO9aQa8t1+AzhAeGM6TqGbsHdHDrx9m7Ym5hjMXSs3xEvNy+83Lx4uOvDzNwwkzrudezTy9fzdFzOPn+eEihoGTnTJQ0vYXPiZvzczUTF09UTT29Phzr5fTXeGfBOsQmrq4vjKM/BrQYTlx5HRl4Gwd7BlZooLBi8gB/3/lhiq8uFSsmIiNQIn2771D7j59ky8jLYnGj2zUjPTWfiiokOz9xjjsYQHhDO86ueJyMvg0d/e9ShLweYM3aeOeIA4Iqvr6Bfk36sT1gPOLZKlLbjZFGJCOCQiFSkMV3HcHXzq7luwXXF1rm7493c1PqmIuusHLaS3ad20yGogz0ZyV/N1WKxFLmS7JkjO16+7GX8PfzxcPUAoH9Yf4e60/pOY/7u+QxuNdhedk+ne+gZ2pNVR1fZF5rz93TsX9Dcvznt6rXD18MXL1cvznZvp3vxdvMmsllkoWP5Xr/8dRIyEkp87OFmcfxadHdxZ8zFxY+OqUgtA1syrvu4Knmv6kbTn4pItWIYBkfSjhR6bv7Vjq+KPWfJgSUO+/uT99v7X6w5tob7ltzHDQtvcGjez59Ua1nsMm5YeEOxjx/OHDlxZr+Mvcl7i42nV2jpOmmey/Utrrdvn9nSMztqNpN7Ty7ynCDvIJr5N3OY1KpbcDdubl3QB6VzUGea+TdjXLdxgPlFn8/X3ZceoT0c+neUZT6VG1reUCgBOVN97/qM7jyaYJ9ge5m7izvdQ7o7rA1zdsuFq4sr866bx0dXf1TkYzYfdx9Gdx5d6PHOmep61T1n/ws3F/2N7gxKRkTkvCVmJjqs+XEuu0/t5ttd3xaadXR9/Ho6f9qZa767ptD8CsW1MEDRicHqo6vJtebah0tm5mXSxK+J/fiOkzvIteUy9rex7E/eX+L1SxIRGlGorKhZL0vyVM+n7Ntn9lEY3m44D3R5gEsaXsL47uPt5T1De3Jl2JUUJX/ERbt6BaM8pl461SF5MTATvXs63cOSW5Ywqdck+7GzH1MAeLs7JiPfD/megeEDARzOPV9nP6o6m8ViqfRl7jsEdajU60vRlAKKyHnL74C4ctjKIpvxz5Y/gVcd9zr2SbtaBrZk7G9j7XWmrZ3GHe3uwDAM0nLTyLKWbf2MR397tFDZmYu4vfXPW1zT/JoyXfNsnq6eTOk9hWsXXGsvc7G42B9RlNa/2v+LLg26sPzwckZ2GMm7G94lz5ZH+/rt7V+OhmHwePfH7X/51/euz5eDvuTLHV9yMuskK4+Y07Hnd7B85OJH8HX35fqW1xeaqvzMVpbQOqE08G7AVc2uolVgK4d63YK7sT5hPUPbDHUobxHQgtf6vcYzEc+U6uddWne2v5OFexY6PMKpaqM7jQYoNtmTyqF5RkTkvOTacun2WTcA3r/qffo0Kjy999ny51O4ufXN/LTvJ7Kt2bza91UmrZhk/6sdYGDzgaw4soK7O97NW/+8Veg6+aMPzpefux+puallPu+2i27jud7P8dyfz/HD3h/oGdqTp3s9TYvAFgxeOJh9yfuYOWAm7298n02JmwD4+cafaejbkDf+eoMvdnwBUKj/SlkdTTvKw9EPk2PN4bsbvnPo7HmmhIwEkrKTuKjuRaW6blpOGnuS9tClQZdKb5HIl2PNKXMyJ9VXab+/lYyIyHlJzUm1ry/y0qUvMbjVYH7Y+wMHkg/wyMWP2L/EtiRusX8RDvhmAACXN7mc3w//Xub3fK3fa7Sp24Y/Dv/Bv9f9GzCHa5a29aRTUCd7h1d/D3+W3LKE6Nhonl75dLHn3NT6JgaGD6SJbxNWHFlBbEos47qPw9PVs8j6ydnJpOak0sSvCU/8/oS9T0p+4pGSk8L/rf0/rmtxHb0bFb3QaFmVNGxZxBk06ZmIVIkzlx+Pz4gH4JmVzwDmcMteDXthtVm5/efbC52bmlO21oj7Ot9H9+Du9GlsJj/5s2YCdAnu4vAYpiTD2w23ryp7VbOr8HH34fqW13N52OW8v/F9bmx1Izf+cKPDOfd3vp9Gvo0A7POPlCTAM8D+CGN059EsPrDYYXE5fw//IufeOB9KRKSmUgdWEWHj8Y0kZiZiM2z2USw2w8ZfcX+RkpNi38+zmfNpHE07ynsb3+NU1imHZORQ6iGHNVvu+d89/LzvZ56Peb7I980fMlta7eu1tyci4Djy4fImJa+W2qF+QcfE7iHd7dv5U3GDmSA80fMJ+8ycAK0CW/H1dV/bE5HyuKjuRcTcHsPzvZ8v9zVELmRqGRGp5TYf38y/Fv3Lvu9mceP9q94nPiOep1c+TecGnZk7cC4Tfp/AkoNLeCbiGT7d9imHUg9xIPkA93a6137uwj0L2ZLouPR7fgtERTi7s+SljS8lxCeEa8Ov5bY2t/Hdru84lX2Kk1kniQiNwMfdxz4F+JM9n+TR3x7l4a4POyQgZw73PVP+Y5+bWt9U5PojZXXm1O8i4kjJiEgtd3afjTwjj18P/Mq+5H0AbDq+iRnrZ9gnwHp5TcGjhUX7FxXqsJo/K2lZuLu4F7sKblO/psSmmivVBnoGOhwL8g5i6a0Fa5ssGLwAi8XCgeQDhNYJxcvNi18P/Epj38Z0DOrIiqEr7I8yRnUcxYrDK+wrpp5tweAF/BX3F9e1LH7yMBGpGEpGRGqhxMxEXlnzCh2DOjosZpYvIy/DYX/XqV3FXuvZP58973i6hXQrtr9HkHdQQTLiFVjidfITjeYBze1lUc2jCh0HGN99vMPcHWdr4tfEYV4SEak8SkZEapHtJ7az5OASPtz8IYC9teNsqTmpDlOjp+WkVWgcg1sOJtgn2B5H56DO9mRkQo8JbD2xlV/2/wI4Tgse4FFxc1qISPWhZETkAmUYBieyThDkHURqTipv/P0G83fPL9W5Zz+6OXvNltLqHNTZPr/GmQI8AxjUYpA9GQkPCOeOtncQHRvN9S2vZ2SHkZzMPMmauDXc2+lebmh5Ax4uHri7upcrDhGp3pSMiNRAebY8DqceJtgnmNScVELqhABmAvLrwV/pHNSZRfsX8eb6N3nk4kc4kHyAH/f9eM7rNvZtzJG0IxUW5+eDPsdqs9L1s64O5XW96lLfq759v5FvI65veT0Te020P0qZGTmT+PR4mvo3rbB4RKR6UjIiUkPsPLmT+Ix40nLSWBu3lu92f2c/dk3za5jQYwJr49baJ+5q6md+ib/9z9vnvLafhx/h/uE82PVBHlz6YLH1wgPC2Z+8n+b+zTmQcqDQ8ZHtR/LJtk/oGdrT3h/D1cWVK8KuYPmh5fbZUq9udrXD45eWAS0Bxz4dnq6eSkREagnNwCriZKk5qcUOL823NXErw34eVmKdm1vfzMmsk/ahrGUxc8BM+jXpR2xKLIMWDCq23m+3/WZfXv7SLy91ONbcvzk/DPmBzLxMhyXlwZyjJCsvi7j0OCwWi319lf3J+8mx5pxzJVURqZk0A6tIDTBnyxymr5vOv9r9i6d6PVVsvWlrp53zWjFHYziaXvqVc8/k42YmD+da9Mzfw7/Q1OWXN7mciIYRRDaNxGKxFEpEwFw8zsfdhxaBLRzKS1ruXURqD83AKuJEyw8tB2Du9rmAuejcyF9G8uzKZ9l2YhsL9yxk58mdbDy+8ZzXOlci4uvuy5o71jis2JqvjnsdoHAysvjmxfRuWJB8nLmA2Qt9XqC5f3Mm9JjAne3vpKFvw3PGKCJSFLWMiDiJzbA5jFKZvWU2gZ6BrE9Yz/qE9Ww8vpEDKQfsrRbFeenSl5i7fS47Tu4osd5r/V7Dx92HedfN4/Hlj/O/g/+zHzuzNaOuZ11OZZ9iWJthNPZtzAdXf8D6+PWFZhC9qfVNDmutiIiUl/qMiDjJizEv8vWur8/7Ot/d8B1Wm5XbfrrNXubr7ktaruPcIH/e/if+Hub/P4ZhsDtpNzf/cDMAy25dRgOfBgAcSjnET/t+4o52d5zzsY2ISElK+/2txzQiTmAYRoUkImD2u2hXvx13tL3DXvb1dV/zVM+n+O/V/8XdxZ3Lm1xuT0TAHLUS4hNi3z+zZSTMP4wHuz6oREREqowe04hUkmWxywj0DKRbSLdCx5Kzk8/7+vW96nNdi+twdzEnAnvk4kf4J+Ef+jbpS5h/GP9qby5+98tNvzgMo80X4BnAhB4TgII+IyIizqBkRKQccq259tlAd53axdvr3+bhix/Galhp4tuE9Nx0xv42FoCPr/nYvmS91Wblu93fOcynURZfDfqKPUl7SM9N5452dzgc8/Xw5evrC7e25E+IVpSRHUaWKw4RkYqkZESkjL7Z9Q2vrHmFGf1n0C2kGw8seYDjmcdZfng5AE18m/DSZS/Z69+1+C7ev+p9OgZ1ZOY/M/lixxflet+nI56mQ1AHOgR1qIiPISJSbSgZESmjqTFTARizbEyRxw+nHeZk1kmHsvuX3F/q69fzqkejOo3YcmKLQ/nQNkPLGKmISM2gDqwi52AzbPbtXFtuqc55afVL565UDH8Pf/o26etQ1iqwFS4W/e8qIhcmtYyIlOB/B/7HlFVTeLXvq1wedjm7Tu0q1Xlnt4ycSwPvBhzPPA6Ya7Lc2+lecqw5dA3uyoaEDYX6h4iIXEiUjIiU4PHfHwfMRzJzr53LlsQt5zijfOZdN48rv7kSMBet83D1YFz3cQD0D+tfKe8pIlJdqN1XpJRejHnRPn17aTT2bWzfDvAMoEN9s+Ppc5c8x4IbFvDloC/txz1cPbip9U3Uca/D7W1vr6iQRURqBLWMSK10KOUQb//zNqM6jqJd/XaFjr+1/q1Cq9/uPLWzTO+RlJ1EU7+mxKbG8mzEs1zd/GqOpR+jUZ1GWCwWtp3YZq/r6erJC31e4IU+L5TvA4mI1GBKRqRWevz3x9l+cjvLDy9n7fC1DsdWHVnFh5s/LPH89vXbOyQTRUnPTeenG39ix8kdXNroUiwWi0Nribebt337zAXoRERqGyUjUittP7kdgMy8THvZpuObeDj6YZKyk855fkTDCHsy8t0N39EyoCUvr3mZ1nVbY8HCy2teZmy3sQR5B3FZ48uKvEZz/+bc3vZ26nrW1UgZEanVyvUbcObMmTRv3hwvLy8iIiJYu3ZtsXX79++PxWIp9Bo0aFC5gxYpq+Ts5HOOcHn898dLlYiAubJtvovqXoSriyuTe0/m9ra3M6ztMH4Y8sM5Zze1WCw8HfE0D3Z9sFTvKSJyoSpzMjJv3jzGjx/PlClTWL9+PV26dCEqKoqEhIQi68+fP59jx47ZX1u2bMHV1ZVbb731vIMXKQ3DMBi8cDCXz7ucmRtmkmfLczje76t+/LL/F+LS40p9zdva3EbnBp0Z221skcfDA8Lta8aIiEjJLIZhGGU5ISIigp49e/LOO+8AYLPZCAsL45FHHmHixInnPH/GjBlMnjyZY8eOUadO0YtzZWdnk52dbd9PSUkhLCzsnEsQS+218+RO6rjXoYlfE8BcA+bF1S8SHhDOkFZDuOyroh+VlNaoDqOYs3WOfX/zyM3ndT0RkdogJSWFgICAc35/l6nPSE5ODuvWrWPSpEn2MhcXFyIjI4mJiSnVNT766COGDRtWbCICMG3aNF54QaMKpHSOph3llh9vAQqShPUJ6/lu93cArI0r/jFiaXi5ejG+x3gGNBvAQ0sf4qGuD51fwCIi4qBMj2kSExOxWq2EhDiuAhoSEkJc3LmbuNeuXcuWLVu49957S6w3adIkkpOT7a9Dhw6VJUypZWZumGnfttqsABxLP2Yv++PwH6W+1oQeE+zb3YK7cV2L6/h44McAdGnQhZXDVjK83fDzjFhERM5UpaNpPvroIzp16kSvXr1KrOfp6Ymnp2cVRSU1zfr49czdPpcnejxBkHcQP+z9wX5s0opJrE9YT7BPcJmvO6nXJO5odweBnoF8seMLXu37Kg19GzrUsVgs5x2/iIg4KlMyEhQUhKurK/Hx8Q7l8fHxhIaGlnhueno6X331FVOnTi17lCJnGLnYHKWSa8tlah/Hf0+/HPgFgPiM+ELnne3+zvcT1TyKrSe2svTgUga3GgzA4FaD7dsiIlL5yvSYxsPDg+7duxMdHW0vs9lsREdH07t37xLP/eabb8jOzuZf//pX+SIVOcvBlIOlSjqKM6DpAFrXbc2QVkN4Z8A71HEvvh+TiIhUnjI/phk/fjwjR46kR48e9OrVixkzZpCens6oUaMAGDFiBI0bN2batGkO53300UcMGTKE+vXrV0zkUmvkWnP5v7/+j0saXsIVYVfYy/cn7+fWH0s3RPzdAe/Spl4bVhxeQbv67YhNjS1yGngREal6ZU5Ghg4dyvHjx5k8eTJxcXF07dqVxYsX2zu1xsbG4uLi2OCyc+dOVq5cyf/+97+KiVpqjUOph5i7bS7zds5j3s55/DjkxzKd/+OQH9mfvJ/LGl+GxWLh5otuBszp3EVEpHoo8zwjzlDaccpyYcm2ZtNjbo9yn39Xh7t4vMfjFRiRiIiURaXMMyJSleLTy98fZO61c+lYv2MFRiMiIpVFq3NJtXEw5SB5tjwMw8AwDBbuWViu6/h5+NGlQRdcXVwrNkAREakUahmRauH7Pd/z7J/P0iOkB3uT9nIq+1SJ9SMaRrDm2BqHsns63sOqo6t45pJnKjNUERGpYGoZkWrh2T+fBeDv+L+LTEQub3K5w763m3ehOuO6j+Pr67+mS4MulROkiIhUCiUj4lQZuRnMWDejxDqDWgzi1b6vOpQVlYyIiEjNpMc04lQvrX6JH/c5Dte9qO5FvHnFm/i4+7D80HIGNB2Ar4cv3m7eZOZlAhBap2DG3+b+zR3WlBERkZpFyYg4TZ4tj0X7FzmUdajfgecueY4mfk0AuKn1TfZj7i7uZGImI/d0vIeNCRsZGD6QYW2HVV3QIiJS4ZSMSJWZu20ujXwbcWXTKzmVdYqo76KwGlaHOl9d91Wx51/d/Gq+3fUtzf2bE+AZwCcDP6nskEVEpAooGZEqsTVxK//31/8BsHnkZj7Z+on9kUtpPdHjCVoFtmJA0wGVEaKIiDiJkhGpEkfSjti3s63Z7E7aXajOteHXlngNH3cfhrcbXuGxiYiIcykZkSqRZc2yb5/KOsWeU3vs+/W86jGt7zTa1dPCdSIitZGSEak0iZmJrDq6itaBrXlmZcFEZAt2L+Bo+lH7fl3PuvRp1McZIYqISDWgZEQqzRO/P8Hf8X8XKn9347v27WCfYF689MWqDEtERKoZTXomFebtf96m0yediPwmkozcjCITkTP1adSH6Fuj6dSgUxVFKCIi1ZGSEakwH2z6AID4jHi+2PHFOet3C+5W2SGJiEgNoGREKsWb6988Z52RHUZWQSQiIlLdKRmRKuPv4c9/+v+HWy+6lXX/WoeXm5ezQxIRkWpAHVjlvPx55E9eXfsqTf2blljv2vBrefaSZ/Hz8COyWWQVRSciIjWBkhEpN6vNymPLHyMzL5MDKQdKrDui/Qj8PPyqJjAREalR9JhGyu1E1olzTuke7B3MvOvm0SGoQxVFJSIiNY1aRqTM4tPjWX1sNWF+YYWOubm4kWfLs++HB4TTvn77qgxPRERqGCUjUmpWmxWbYSPy2+L7fPi4+ZCSk2Lff/qSp6siNBERqcGUjEipbDuxjbt/vZv03PQS652ZiAC0CGhRmWGJiMgFQH1GpESpOalk5mXyV9xfRSYi/h7+PNnzSYeyiNAIAAa1GFQlMYqISM2mlhEpVnJ2Mtd8dw2hdUIZ0HRAkXVmR80mx5pj349qHsWzEc+yNHYpUc2jqipUERGpwZSMSLGWHlxKWm4ae5L20KVBl0LH37j8DdrUawPAhB4TCPQMZFCLQbi5uHHLRbdUdbgiIlJDKRkRu/3J+3GzuBHmb46S2ZO0x37su93fFarfK7SXfVtTu4uISHkpGREATmSe4IaFN2DBwj93/sPMDTOZu31uief4evhWUXQiInIhUwdWASDmWAwABgbJOcl8uPnDIus92OVB+7a7i3uVxCYiIhc2tYwIGxI2MG3NNPv+qaxTxdYd0HQAnq6eNPZtXBWhiYhILaBkRLjzlzsd9uPT44usd3Prm2lTr42906qIiEhF0GOaWs4wjEJlz/35XKGyEJ8QpvSeUhUhiYhIVck4CYsnwb7fnRqGWkZqMcMwyMjLKFSekJlQqOzpiKexWCxVEZaIiFS2k/th/x+w5TvY/zts+wHGbQIXV6eEo2SkljqcepgHlz6It5t3ifU+v/Zzmvg1oZ5XvSqKTEREKpRhwJLJ4O4D/SfCZ0Ng33LHOimHzbJWRU9wWdmUjNRSszbO4kDKgULl93S8h4+2fGTf79ygcxVGJSIiZbb+U3Dzgk63wsl9ZouHdyC0GQRuHmbZqrfMulu+gxO7C1/jkoegfqsqDftMSkZqqcy8zCLLB7UYxIojK9h1alcVRyQiIsVK3A3Jh+HYBkjYAdkpkHkKIp+HHx4x68wf7XhO/VbQ6GLYvaSgrKhEpPsouGZa4fIqVK5kZObMmbz++uvExcXRpUsX3n77bXr16lVs/aSkJJ555hnmz5/PyZMnadasGTNmzODaa68td+ByfpJzkguVWbAQ7BOMj5uPEyISEZFCDAP++awg4Tjb7BLWADuxx3ydqc210GUYtB9stqB4BUDDwst9VLUyJyPz5s1j/PjxzJo1i4iICGbMmEFUVBQ7d+4kODi4UP2cnByuuuoqgoOD+fbbb2ncuDEHDx4kMDCwIuKXckrJTnHYv7P9nQxqMYgAzwBua3MbG45v0CMaEZGKYBhgs4Lr6a9cmxVseXBsEwS1Au+6kLgHLBazfN9yuPhOSD0Gb3cr/ft414XMJAjvB3GbIfOk4/Eb3oFuZ0zlEN7vfD9ZhbEYRY3tLEFERAQ9e/bknXfeAcBmsxEWFsYjjzzCxIkTC9WfNWsWr7/+Ojt27MDdvXQzdmZnZ5OdnW3fT0lJISwsjOTkZPz9/csSrhQj6tsojqYfte9/fM3HdA/pDpijbNYnrOeiuhfh5+HnrBBFRGqm9BNma0ZQa3N/0RPg5gntboDY1XBoNVhcwLCZx109wZpd/PXO1KAdDJ4JfiHw92zIOGGW9Tr9iMawgau7mfBYXMCaYz6myUiEbiPNhKcKpaSkEBAQcM7v7zIlIzk5Ofj4+PDtt98yZMgQe/nIkSNJSkri+++/L3TOtddeS7169fDx8eH777+nQYMG3HHHHTz11FO4uhY9hOj555/nhRdeKFSuZOT8GIbBkoNLaF+/Pbf8eAvpuen2Yz/d+BPN/Js5MToRkRpu6fOw8j8Vf13PABg2Fxp1A8+atSZYaZORMj2mSUxMxGq1EhIS4lAeEhLCjh07ijxn3759LFu2jOHDh7No0SL27NnDQw89RG5uLlOmFD2J1qRJkxg/frzDhwkLCytLqFKEXw/+yhO/P1HksQbeDao4GhGRGsowYO8yyEmHtoPg0Bpz+3wTkfZDwMMXLoqCr08/TvHwhfFbwfPCbqWu9NE0NpuN4OBgPvjgA1xdXenevTtHjhzh9ddfLzYZ8fT0xNPTs7JDq3VWH11d7DEfd3VaFREp0eZv4cdxZt+M5NiS6146Fg7GwOG15n63EeDiZj5aqRMM6QkQ0gmufR0+uxF6PwwDzpj9+vlkiNtibl/giQiUMRkJCgrC1dWV+HjHtUvi4+MJDQ0t8pyGDRvi7u7u8EimXbt2xMXFkZOTg4eHRznClrJ4efXLpOam4mpxfCx2fYvr+XHfj06KSkTESY5uMIfKtrvO7GOx9zdIPgRr3ofQTpCeaHb0bDsIYtdAq0hwcYHv7jHPz0kt/tpBbaD1VRD5gtmCglHQjwPgutOtJ5mnwNPfnPF00uGCzq1nCu1YkZ+6WitTMuLh4UH37t2Jjo629xmx2WxER0czZsyYIs+59NJL+eKLL7DZbLi4mEvh7Nq1i4YNGyoRqQLZ1my+2vkVQKE+IVMvnUpEwwguqnuRM0ITEal8WclmZ06f07NI//mmORspmH0xLBbISiqof2q/+d/YVdDiCtj327nfY/Rv8NdH0KI/dL61oNzeWbSI/pHedQu2i0pEapky34Hx48czcuRIevToQa9evZgxYwbp6emMGjUKgBEjRtC4cWOmTTMnUHnwwQd55513GDt2LI888gi7d+/mlVde4dFHH63YTyJ2udZcXl7zMisOr+DFy160lx9MOWjfvqvDXbi5uDG41WBnhCgiUn6GYU7wtfkbuP4taH6Z2crgUx++HGoOjW07CKy5sOMn85x2N0D9lo79OrILz7fkoLhEpNsI6DMWVr9rtqA0uhgal2EIrhRS5mRk6NChHD9+nMmTJxMXF0fXrl1ZvHixvVNrbGysvQUEICwsjF9//ZXHHnuMzp0707hxY8aOHctTTz1VcZ9CHLy4+kUW7FkAwANLHiiyjpuLMnERqUbyh6LmP9pwcYWcDHD1gBX/hm3fQ8JW8zFIWC8zEQH48fQftu514IwRgmxd4Hj97T+ULR43byhqpuoW/eGGt83t66aX7ZpSrDLPM+IMpR0aJKZOn3Q6Z53RnUbzaDe1TolIFco4ac74efbKsDnpMOsycw2VfEFtIHFn5cRx68ewYxFs/rqgrNHFZivLvuXQ/S5zUbnFT8H6z8x1Xu742lzdtvNQ8Cu6j6QUVilDe+XC4WJxOXclEZGKcmwjfHAFtBkIQ+cW9Kc4dQB+e8UxEQHHRKSoScF8Q8zHMGfPMnq2O74G/0ZmS8cXt5qPdNoNhg43mjFs/hbu/6Ogs2jDM2aeHvRv85WvUdeyfGIpAyUjF5hcW26p6p09skZEpNIc/Qc+vNIcVbLjJ3ghEDrdZo4o2bOk6HPaDIKdP0Nwexg03UwWdv4CjbubLRMedcx6NhukHIafHjNnN71ljjn6Zd8yqNcS6oUXXPPRfxzf44Z3IOoVqBNUKR9bSk/JyAUm+awOWRYshAeEk5aTRkJmgr28X5PqsyaBiFygstPgjdaQm1H42JmPSM7UsIs5OuXsRzkAnW8rXObiAoFN4favIC+rYE6OVpHnjs/NA9yUiFQHSkYuMGdO8Q7wx9A/CPQKJNuazZ5Te2js25i4jDja1mvrpAhF5IKSnQbzhpsdUFtfbbZE/PKU+QglPcGxbusos1Vj/SeO5e0HQ4974O+PYOBrRSci5+LqXjCXh9Q4SkYuMGm5aQ77ddzNpkxPV086BHUAINArsKrDEpGaLuOk+ZglJw2OrIddv8Kmr8C/MaQcMescWFH8+Y/+A/VamNs3vGU+ctm6AK55tWAOkBaXV+5nkGpLycgF5uGlDzvsu+svBRE5X7lZ8N6lkJ1iJiNnyk9ESvLk/oKEI1+bgeZLBCUjF5Svd37NiawTzg5DRC4kq96G/z1b+vpXTTWXqp9/nzkt+sV3grtX5cUnFwQlIxeQV9e+6rD/222lmMZYRKQoNqs52dhvLxd9/NJx8M9cc0SMYTWHyl7xLAS1Mo8PL6aDqkgRlIxcAPJsebwQ80KhYb1B3uolLiJn2fe72fcjvB/kZZszmRo2c2rzmz40H6csehJ2/VL43MsegwN/QnhfGDAZrnoBrHmQdNCcal2knJSMXADWHFvDwj0LnR2GiFRneTnw+S3mLKLF+eBy8PArelXaCbvBJ8gcSnsmVzclInLelIxcALLPnpkQ6BHSwwmRiEi1kJYAJ/aao1d+esxs7WjUteREJF9OKlhcofdDZgKz9n1ocy34Bld62FJ7KRm5AGTkFUwo9PaVbxObEsu1La51YkQiUqkSdkDqUWh5pblvs5kLwfk3hm0LIeadwuf881nprt3sMhj0BgS3M/d73qtERCqdkpEaLNuazaJ9i0jMTATgqmZX0T+sv3ODEpHK926E+d8ON0GzPuZkXz+OLft1et0Pba4xF4Xb9Su0vQ6adHes0+Ci849X5ByUjNRgH276kPc3vW/f93X3dWI0IlLpbDZzhEu+rfPN19n8m5jrtYA5K+qepWYn1Yv/ZQ67/fUZs/WjYZeCc5peUrmxi5RAyUgNFh0b7bDv66FkRKTGsebC3t8grJe5VD3Alu/AMKDTLea+YcAvT8LaD0q+Vqdb4Yqnzb4i1jyw5YK7Nxz+GzKToNUAc6Xae4tZnE7ESZSM1FC5tlz2JO1xKPPz8HNSNCJSakfWwbGNkLAd0hMdWza63H762DZzf93HZstGaKeSExFPf7jrJ8eWDlc38wXQRB3apXpTMlJDFTWU189dyYhItRW3BWZHFZ5O/Uwbv3TcP7Ci8Hovbt7mjKaZp8DVE+5bbraEaJZTqcGUjNRAX+/8mv+s+49938vVi/CAcC4P0yJTItWOYcCfM2Dp86WrXzccTu03t109zJlQDau53+MeuG66uX10g1ke0r6CAxapekpGapgNCRt4cfWLDmVzrplDx6COTopIROwMA/ZEw8E/zUXl/voveAVCVlLR9cMi4I6vzUc3c2+C4A7w4J+QGgcb5prDajNPwVsXm/XbXVdwbqOulfxhRKqOkpEaxGqz8szKZxzKLFjoUL+DkyISqcUO/QUWF8hINOf3OLkXvh5RuN6ZiUiTnnDJQ5AWD93vMjuXgtmxdOxGs++HxQL+DaHfE+Yx77pw9cuQfhzC+1fuZxJxEiUjNcjXu74mNjXWoew/V/wHi8XipIhEaqm04/DRVYBR+nOipsElD5rJRlHqNi/+3D5jyhKdSI2jZKQG2X1qd6Gyup51nRCJSC2SnQprZkGn2yAgzGwJWTmDEhORDjfCyf0Q0sFs2WjSwywTkSIpGakh9iXv45td3xQqr+NexwnRiFyg0k+Yc3MsfR48fKHttbD+U9i6AJa9ZI5aST8B2cmO53n4FoySuWU2dLy5ykMXqcmUjNQQz/35nH3b3cWdXFsuoInORMrt+E44scccHvvlMDMJOdtfHzrun9znuN+kl9ni0fsh89GNLc/s7yEiZaJkpIY4nHrYvh3sE8yRtCMA1HFTy4jIOdls4OICe5dBTrrZ8fSrO8p2jaa9ITamYL/9YLj1k4I+IL4NKi5ekVpGyUgNYRgFz6cDPAMKkhE9ppHa7sg6c24On3qFj+Wkw88TzMcsrQbAjp9KvlbdcOj7OMRthnVzwJpjlg+dC20GmfOFhHQ0+4B41y2+M6qIlImSkWps16ld5FhzaOrflGxrtr38zAXx3F3dnRGaiPNYc80kwaMOxK42ZzUF6D4KGnY2JwlzcYOsZDNR2f6DebyoRKTrcHMK9rBe4ObpeGzg/5nTtaceM68L0Hd85X0ukVpMyUg1lZGbwc0/FN0Jrp5XEX8BilyospIhLwdcXGHOQDi+wyx384a8zIJ66+aU/dpD3i3+mMViPnrR4xeRSqdkpBp6efXLfLXzqyKPzRwwk5VHVlZxRCJVzGY112n5/uHi65yZiJSkzyOw61dI3GXuN+9rrmB7zbTzDlNEKoaSkWqouEQEoF+Tfuw8ubMKoxGpBIZhPmpJOQLHd0HcJuhxN8wfbXYyLYumvaHtIPjfs4WP3bkAWl4JV78EXw2HY5tg6Gdmfw8RqTaUjFQzVpv1nHWGtxvO9pPbiWwaWQURiVSCH8fC+k8cy357uXTnPrHX/O/6T80+H34h5miZsEvM9Vp+fw02fgV3/eg4q+mwzysichGpBBbjzGEa1VRKSgoBAQEkJyfj7+/v7HAqVWJmIld8fUWRx+5oeweTIiZVcUQiFWjb9+aEYmfP11GU4d9CWoJZN+gi8PSFNtdqBItIDVLa72+1jFQzsSmOa8/c1/k+WtdtTY+QHgR6BjonKJHy2vYDeAdCeD9zZEpRC8mdySsAHlqjicNEahklI9VIem46IxePdCi7qO5FRDWPclJEIuXw9xz4aZw5sZhhM8u6jSz8WAZgShIcXQ9uXrD9Jwjvq0REpBZSMlKNTP97eqEyTWomNYo1z0xEoCARgaITkcvGm49cGnc390M6VHp4IlI9KRmpRr7e9XWhMm83bydEIlIMmxU2fwMNu0JwW9i3HH4cBxEPQFo8rCycUDvwrgcPrIADK6HTrVUQsIjUBC7lOWnmzJk0b94cLy8vIiIiWLt2bbF1P/74YywWi8PLy8ur3AFfqJYeXGrf9nT15F/t/kX/Jv3p2qCr84ISOdvq92DB/fBuBDwfAJ8OhlP7YfFThRMR/yYw/Du46+eCsrt+goAm0GWYOYmZiAjlaBmZN28e48ePZ9asWURERDBjxgyioqLYuXMnwcHBRZ7j7+/Pzp0Fc2NY1BveLiEjgWdWPsPqY6vtZR9e/SEXB1/sxKik1sjLNqdOPzMxyMuG7FSoEwQrpkP0C2Z5n0dg5+JzX7PL7TD4XXNhunxPHwN3b42EEZEilTkZmT59OqNHj2bUqFEAzJo1i59//pnZs2czceLEIs+xWCyEhoaW+j2ys7PJzi5YiyUlJaWsYdYYyw8td0hEwFwIT6TSpcabLRyZp+CBlRDcHlb+B/54HfKyICAMkg8V1F/1dsnXa94XrnzOXOfl7KTDw6fi4xeRC0aZkpGcnBzWrVvHpEkFc124uLgQGRlJTExMseelpaXRrFkzbDYb3bp145VXXqFDh+I7q02bNo0XXnihLKHVWMnZyYXK/D0u7LlUpIoc/Qc+vs5cubZeOFw+Eda8B4l7oOvtsOELyEkz6866rPD5ZyYiZ7p0LPR+BDZ8bk7ZfvuXZnlgc8fWEBGRUirTb47ExESsVishISEO5SEhIcTFxRV5Tps2bZg9ezbff/89c+fOxWaz0adPHw4fPlzs+0yaNInk5GT769ChYn4pXgCSspMKlQV4qGVESsmaW7CdmwmH/jJHtJzYC/+96nSyYZgThy24z0xQclJh7QcFici5NLsMnomHvhPg2jdgwBRz8bjLxsHDa6BeC/OlREREyqnSR9P07t2b3r172/f79OlDu3bteP/993nxxReLPMfT0xNPT88ij11oimoZcXd1d0IkUmNYc81hsylHYFY/MzG45CGIXQ1bvi39dQKbmf1D0s76Q8K/CaSc/mPhimeh3XXg7gUDnqu4zyAicoYyJSNBQUG4uroSHx/vUB4fH1/qPiHu7u5cfPHF7NmzpyxvfcHal+w4LfZvt/3mpEikRrBZ4YP+ZgfTbnearRwnU2HRhKLru/tA97tg9bvQpOfp5CMBol42F5fLyYAt38HF/wI3T7Mjq80GS56DBm3N9xARqWRlSkY8PDzo3r070dHRDBkyBACbzUZ0dDRjxowp1TWsViubN2/m2muvLXOwF5ItiVt4Zc0rbE7cDEA9r3rMuWYOQd5BTo5Mqp2di82RKC0uh7/+C/FbzPJlLxVd38UN2g82kxA3L7ND6TXTiq7r7g0R9511vouZrIiIVJEyP6YZP348I0eOpEePHvTq1YsZM2aQnp5uH10zYsQIGjduzLRp5i+/qVOncskll9CqVSuSkpJ4/fXXOXjwIPfee2/FfpIa5vafb3fY/+jqj2gR0MJJ0Ui1te37gvVcIh40O6CebfQy2LHInIBs0BsQ0NRc48VVcxqKSM1Q5t9WQ4cO5fjx40yePJm4uDi6du3K4sWL7Z1aY2NjcTmjI9upU6cYPXo0cXFx1K1bl+7du7Nq1Srat29fcZ+iBjmYcpApq6Y4lIUHhNOqbisnRSTVVmaS48JyZyYiTXqanUb7TzJHyjTurj4dIlJjWQzDMJwdxLmUdgnimuD+Jfez6ugqh7L7Ot/HIxc/4qSIpNr64w1YVkQn79G/QeNuVR+PiEgZlfb7W+24VSw1J7VQWWid0k8IJxe4tR/Cin/DRVGw7mOzrN0NEPUKeNQBn3pODU9EpDIoGalCydnJHEw5WKi8bd22TohGqo3cLMhIhLm3wPHtZll+IuLhBwNfA/+GTgtPRKSyKRmpQnctvouUnMJT27evXzv7zwjwy8SiO6UCNGgH9y4FT9+qjUlEpIopGalCe5IKz60yvf90XLV6ae0Tvw3e6130sRZXQMI2uOFtJSIiUisoGXGy7iHdnR2CVLWdv8CXw4o+dsPb0G1E0cdERC5QSkaczNddf/le0OI2w/4/zAnIZl8DcZscj1811Vx4zpoH1hytbisitZKSkSqSbc0uVHZJw0vwcPVwQjRSqfJyYOkU2LMUEneZZb8+XbjeFc9An0fNbVc3TVImIrWWfvtVkbOH9M64YgZXhl3ppGikXBK2wz9zzQnHml4CWckQvxXqtzSnYPeuayYgK/9jrpJbEjcvuPzJqolbRKSaUzJSBU5mneSjzR85lLlZ3LBYLE6KSM7p2CawuEBwe3NV283fmElG5qnyX7Npb2h3PaQchfDLKy5WEZEaTslIFXhlzSv8euBXh7K03DQnRSMlyjgJ718OybHnf60ud0B4P6jTwBwd03uMuQidiIg4UDJSBc5ORAAuDr7YCZFIsWw22P0/+N8zJScit8+D4Haw42f4dZJZFnQRNO4BG7+Aga9DUCtIT4TOtxWc1zqycuMXEanBlIxUsrScNPw8/Ox9Rib0mEBks0ga+TZycmTiIPp5+PPNkuv0vBfaXGNu934IWkWCYTWTE2su9HkEQjSBnYhIWSkZqWQ3LLzBnoiM6jCKf7X7lyY5qw5y0mH9p5BxAlZMN5OKfFe9CM0vg0VPQI+7ze26zQpfo8FFBduu7kpERETKSclIJTIMg+OZx+37IzqMUCJSHeTlwDs9IeWIY3nd5nDXIghobO6Pjq7y0EREaiP1pqtEmXmZDvv1vLTiaqXLyzE7oQIYBqz/DKJfhNzTP4sTe+G/AwonIgB9JxQkIiIiUmXUMlKJzh4x42JR7lfpPr/ZnPG01/3gFwrRL5jle5eZHU03fWXuu3qYM556BcKQdyEnAzrd4rSwRURqMyUjleSPw38wa+Ms+/4NLW9wYjS1RMZJMxEBWPu+47Gj681XvnuXQr0WYNjAK6DqYhQRkUKUjFSSh6Mfdth/JuIZJ0Vygcs4CWtmgYcvbJ1fdJ3r3zJnTvUNhpw0uPbf5vBbERGpFpSMVIFWga3wcdcCaOVmzTPn/4hdDTd9YE4gZrPC7/9XsPbLmfo9CXuj4cg6uPpl6D7SfImISLWkZKQKHEo95OwQag5rLix8CI5vhzu+hu0/wS9PFByf2avk87vcDlc+Y75ERKRGUDJSCc5eobeoFXulGDt+gs1fm9vT25XunCufNTusxsZASy0+KCJS0ygZqQTvbyzoPOnn4cfDXR8uobaQcgzmDQd3Hziwoug6bl6Ql2Vud7rVnKxs7zJzv9/plpOLoio/VhERqXBKRirYvqR9fLj5QwAaeDcg+tZorc5bnDUfQHoC/D3bTC7yuXqCTz1IPQb9n4Z+E8DFFeK3mTOhetSB3Czz8c1F1zgvfhERqRBKRipYbGrBImserh5KRIrzz1zHviD56gTD4Jlw0dWFj5053bq7F9zwduXFJyIiVUbJSAVLyEhwdgjVS/xW+Owm6P8UNLvUnAdk0QTHOgFNYeT35rwfIiJS6ygZqUC51lzm7Zzn7DCqj7xseK+Puf3TY4AFMBzrePjB6GXg26CqoxMRkWpCyUgF+mHvD+w6VTDvRa2a/t2aC+mJ4N8QDvxpjog5sx8I4JCIhPeDK56Bxj3AVf8MRURqM30LVKADKQcc9i/4ZOTwOljxBnjXg0Or4cSekusHXQT/mg/egeDpVyUhiohI9adkpAKdzDJXi63nVY+UnBSe7/28cwOqKFnJsOFLSDpoznja8WZIOQp/vgnZKec+P7CZ2Uoy6N8QGFb58YqISI2iZKQCncg0H0s81v0xBoYPxNPV08kRnae4zWbSseAByDxZUL5nafHnNGgLHW+B314y96NegV73gWGAm0flxisiIjWSkpEKlN8yUt+rfs1PRPJyYM615275CIuA3mPgt5eh98PQbYRZ3vUOcPVQx1QRETknJSMVZM+pPWw/uR2Aet71nBzNecpKhk8Hl+4RTJ0G0P4G83WmgMaVE5uIiFxwlIxUkBt/uNG+3cyvmRMjOU/WXHNm1KP/mPv1W8H9K8CwgsXFHK4bGwMxM+HgnxDxgHPjFRGRGk/JSAVIzUl12Pf18HVSJOVgGLD7fxDcDjbNg2UvOR5v2hs8fAr2PepA20FmefJhaNi5auMVEZELjpKRCrDj5A779jMR1Xzp+t1LzAXmwnqZ84HsWQKnDhRdt9315lwgRfGpZ75ERETOk5KRChCfEQ9ARGgEw9oOc3I05/DjWEg5AqvfLble7zFw9UugtXVERKSSlWtWrpkzZ9K8eXO8vLyIiIhg7dq1pTrvq6++wmKxMGTIkPK8bbW15tgaoBp3XN29FD6+Dr4YZiYiZ/JvDJeNN/t+DJgCraPM/aiXlYiIiEiVKHPLyLx58xg/fjyzZs0iIiKCGTNmEBUVxc6dOwkODi72vAMHDjBhwgT69u17XgFXN7tP7WbhnoWAOaTXqWxW2PyNOTeIf2PodAvs+Bm+vrP4c8ZtAZcLfKZYERGp1sqcjEyfPp3Ro0czatQoAGbNmsXPP//M7NmzmThxYpHnWK1Whg8fzgsvvMCKFStISkoq8T2ys7PJzs6276eklGKIqZN8teMr+3ZmXqbzAjm535yc7NDqgrIF94FLET/ijrfAlm8hapoSERERcboyJSM5OTmsW7eOSZMm2ctcXFyIjIwkJiam2POmTp1KcHAw99xzDytWrDjn+0ybNo0XXnihLKE5RUZuBksOLrHvN/dvXrUBxG2BpFgz4fjtJTi2sXAdWx6EdIKrngd3H2h2ehXdqFfMOUJEREScrEzJSGJiIlarlZCQEIfykJAQduzYUeQ5K1eu5KOPPmLDhg2lfp9JkyYxfvx4+35KSgphYdVvTZOpq6dyKvsUAKM7jea2NrdV/ptmp5nzfCTuhl8nFT7u6gmP/gNLJsOBldBmoJl4nDk8F8AvpPC5IiIiTlCpo2lSU1O58847+fDDDwkKCir1eZ6ennh6Vu/p1NNz0/l5388A/Pfq/xLRMKLy39SaB59cVzAh2dl86sO4zeZcILd8VPnxiIiIVIAyJSNBQUG4uroSHx/vUB4fH09oaGih+nv37uXAgQNcf/319jKbzWa+sZsbO3fupGXLluWJ2+l2n9oNQAPvBlWTiMRvg2UvFp+ItBkEN84yExEREZEapEzJiIeHB927dyc6Oto+PNdmsxEdHc2YMWMK1W/bti2bN292KHv22WdJTU3lzTffrJaPXkojPTedN9e/CUDruq0r/w3jt8J7fQr2Lx0HEfebiUdOhtlpte114Ope+bGIiIhUsDI/phk/fjwjR46kR48e9OrVixkzZpCenm4fXTNixAgaN27MtGnT8PLyomPHjg7nBwYGAhQqr0lGLR5lXxQvqnlU5byJYcCiCZCeCNsWFpT3fRwufwrcTj/G8gqADjcWeQkREZGaoMzJyNChQzl+/DiTJ08mLi6Orl27snjxYnun1tjYWFwu8OGi+YkIwBVhV1TOmxxdD3/917Gs/yToX/TwaRERkZrKYhiG4ewgziUlJYWAgACSk5Px9/d3djh0+qSTfXvTiE1YKnqm0mObYP59cLwg6WHkjxDer2LfR0REpBKV9vtba9OcpwpPRKy5MO9fkHSwoKxpb2h+Yc1cKyIikk/JiLMcWW/29/BrCCf3wi8ToUV/c/KyfGM3mcctLlonRkRELlhKRsoox5pj3/5s4Gflu8iaD+CXJwqXH1xZsN3ueqjbrHzXFxERqUGUjJRRUnaSfbtjUBlHBG37ATZ/DTsXF18nLAKueNr8r4iISC2gZKSMpsZMtW+7FbUIXXFSjhZePbduczBs4F3X7BPS5lpz7Rg9khERkVpEyUgZ5Nny+P3w72U/ce9v8NkQx7JRvxQsWiciIlKLXdgTglSwL7Z/UfaTtswvnIjc/JESERERkdPUMlIG/yQUrAszvf/0c5+wewl8O6pg368RjFoE9cIrIToREZGaSclIKaXmpLI0dikA71z5DpeHXV7yCUfWwee3mNue/nDXT9CwSyVHKSIiUvMoGSmlT7Z+Yt9u5Nuo5MpZKfDFMHPb4gJ3L4aQDpUYnYiISM2lPiOltD5hvX27sW/j4iseWAmvhkF6AgSEwX2/KxEREREpgVpGSsndxR2AWy+6FR93n6IrLXgANn5ZsN97DDTsXAXRiUhlysmzkWez4ebigoeb/oaTAtl5VjxcXSp+aZByyLPayLHayn2+p5srri7O+RxKRkopPj0egKuaXVV0haRDjolI38eh571VEJnUFjabQWJaNqVZ2TInz8aOuFSy86zlfj+rzWBXfCppWXnlvkZFycq1sSMuhVxr1a/rmWezsfd4OlabgburhRZBvk77hS3VS67Vxt7jadT18SDE38upsdgMg/2J6WTnlT8Zmf9QH7o1rVuBUZWekpFSis8wk5GQOiGFDx7fBTN7Fuxf8hBc+VyZJy9Lz87jaFJmmc45mpyFYRg0DvS2lxnAwRMZHE/NLtO1KtPRpMxCny0z18rOuFRybeX/n6c2ScnMIzkz19lh1Gq5VoOd8anODkOqmRPpOZxIzzl3RSmWkpFS2HZiG2m5aQCE+oSahYZhPpbZ/gPknvEle9WLcOmjpbru4VMZHEvO4s89iayPTSJmb6JT/vKTmsWtlH+Vh/h7EVbP+9wVSxDo7UGrYN9qMSlwk7rehAac3+cpr2A/T5rV92Hf8XR96YiDej4epGblkmtz/u9ufy83LgrxK/f/r55urhUbUBkoGSmFoT8NtW/b+4ts/hY2feVYMbApdB1e4rWW7Yhn7JcbSMvJwyjm3269Oh6lji0r14phgLeH4z8iLzcX2jb0L/UXV2Vzd3OhXahfoX/sYfW8nd68WVNYLBZaB/tSx1P/2zpLx8YBzg5B5IKk32rnkJWXVbgw5Rj8NK5gv8UVcPtX4O74pXosOZO/DpziyKlMYvadYG9CGkfOelTRONCbEH9Pru3UkIYB3gxoF4yXu/OyUxERkaqmZOQc9ibvLVy4/QfISYOQjhD1CjTtDW4FrRmpWbk88uU/LN95vMhrRoTX47VbOlO3jgf+Xu6VFbqIiEiNoGTkHA6lHrJvz46abbaKrDs9AVqHG6GFORPr/sR0vl13iJ1xqSzdnuBwjcsvakDXsEC6Ng2kY6MAGvh5Vln8IiIi1Z2SkXM4kXkCMIf09rS5wfS2BQdbXGHWSctm6PsxJJw1eqVPy/pMu6kTzerXqbJ4RUREaholI+eQn4zUT4mHD/oXHAjpxBZa8vx7q9hwKIm80z2pb+/VlGs7hdIm1I9gP3XMFBERORclI+dwIut0MrJ/VUGhizvbIj/h/rnr7R1SWzaow2u3dKF7M+dMGCMiIlJTKRk5h/yWkaA88xFMrn8z3vCdwPsf7bDXGXNFKx7o3xJfDbkUEREpM317nkNiZiIA9a02Dlz5Ljf9HszJhBxcLHBl22AevqIVFztp+lwREZELgZKRczietB+ABnlWnt7WhJPpaYQH1eHDEd1pFezn5OhERERqPiUjJbAlxXIyLx0sFvzdA1l1IA0XC3x6dy/C6hWzcq+IiIiUidbCLkHSshfJOz3J/+RT5jTvI3o3VyIiIiJSgZSMlOB4/EYA3PI8WG7riYebC49FXuTkqERERC4sSkaKs/5TTqQcBMCW5w/A9Nu6EOCj6dtFREQqkvqMFMVmg99e4biruWCdhfrsfOkapy6vLCIicqFSy0hRTuyG1GMkupq3p0W9hkpEREREKomSkaIcWQfAHH9z/pC2DRo5MxoREZELmpKRopw6wE4Pd5JPP8TqEtrCufGIiIhcwJSMFCU9kUV1zOG7rnhyfcvrnRyQiIjIhUvJSBHyUhPY6ukJwAOdxuPjrnlFREREKouSkSKsSD3EGm8vAPo26+LkaERERC5s5UpGZs6cSfPmzfHy8iIiIoK1a9cWW3f+/Pn06NGDwMBA6tSpQ9euXfnss8/KHXBVGOdx0r59UaAmORMREalMZU5G5s2bx/jx45kyZQrr16+nS5cuREVFkZCQUGT9evXq8cwzzxATE8OmTZsYNWoUo0aN4tdffz3v4CuDkZuNzZwBnotdB+DuqknOREREKpPFMAyjLCdERETQs2dP3nnnHQBsNhthYWE88sgjTJw4sVTX6NatG4MGDeLFF18s8nh2djbZ2dn2/ZSUFMLCwkhOTsbf378s4ZZZyp4lXPrneACeaP0dI/qoZURERKQ8UlJSCAgIOOf3d5laRnJycli3bh2RkZEFF3BxITIykpiYmHOebxgG0dHR7Ny5k379+hVbb9q0aQQEBNhfYWFhZQnzvCTFbwbAwwadw4Kr7H1FRERqqzIlI4mJiVitVkJCQhzKQ0JCiIuLK/a85ORkfH198fDwYNCgQbz99ttcddVVxdafNGkSycnJ9tehQ4fKEuZ5OXbyMABeVjfahvpV2fuKiIjUVlWyNo2fnx8bNmwgLS2N6Ohoxo8fT4sWLejfv3+R9T09PfE8PbS2qh1NOgqAl+GBl7umgBcREalsZUpGgoKCcHV1JT4+3qE8Pj6e0NDQYs9zcXGhVatWAHTt2pXt27czbdq0YpMRZzqefgK8wde1jrNDERERqRXK9JjGw8OD7t27Ex0dbS+z2WxER0fTu3fvUl/HZrM5dFCtTuKspwAI8Wjg5EhERERqhzI/phk/fjwjR46kR48e9OrVixkzZpCens6oUaMAGDFiBI0bN2batGmA2Rm1R48etGzZkuzsbBYtWsRnn33Ge++9V7GfpIIct6QDboQHhjs7FBERkVqhzMnI0KFDOX78OJMnTyYuLo6uXbuyePFie6fW2NhYXFwKGlzS09N56KGHOHz4MN7e3rRt25a5c+cydOjQivsUFSTtVDzH3ayAGx3CL3F2OCIiIrVCmecZcYbSjlM+XztiFjFu6+MccXdj7rVz6dJAU8GLiIiUV6XMM3KhSzh6kJTTrTr+HpU7uZqIiIiYlIyc4dTxw6S6KhkRERGpSkpGzpCeftS+rWRERESkaigZOYMt9wQAnrhqgTwREZEqomTkDIbNnGPEz9XLyZGIiIjUHkpGTsuz2jAsqQAEuvs6ORoREZHaQ8nIaSczcshwzwSgSZ2GTo5GRESk9lAyctqJ1GyS3XMBaOLf1MnRiIiI1B5VsmpvTXAqKYk4dwsATeq2cnI0IiJitVrJzc11dhhSAnd3d1xdz3+FeyUjp6WfOsphN/N2hAW2cHI0IiK1l2EYxMXFkZSU5OxQpBQCAwMJDQ3FYrGU+xpKRk6zJuzmsLt5O5r4hTk5GhGR2is/EQkODsbHx+e8vuSk8hiGQUZGBgkJCQA0bFj+/pZKRk6zntpM2unZVxv5NnJyNCIitZPVarUnIvXr13d2OHIO3t7eACQkJBAcHFzuRzbqwHpaRvoeAAIMT7zcNM+IiIgz5PcR8fHxcXIkUlr5P6vz6d+jZOS0ZFsSAHVdNceIiIiz6dFMzVERPyslI6elGGkA1HcLcHIkIiIitYuSkdNSLFkABHs3cHIkIiJyofj4448JDAy07z///PN07drVafFUV0pGTkt1zQMg1DfEyZGIiMiFasKECURHRzs7jGpHo2mAjJw8slysgBvB/qHODkdERC5Qvr6++Pqqb+LZ1DICnEjJJNPFAKC+X7CToxERkeqif//+jBkzhjFjxhAQEEBQUBDPPfcchmF+Z5w6dYoRI0ZQt25dfHx8GDhwILt37y72ekU9ppk9ezYdOnTA09OThg0bMmbMGADuvvturrvuOoe6ubm5BAcH89FHH1XsB3UyJSNA0ol4UlzMW+FfR49pRESkwCeffIKbmxtr167lzTffZPr06fz3v/8F4K677uLvv//mhx9+ICYmBsMwuPbaa0s9zPW9997j4Ycf5r777mPz5s388MMPtGplLkly7733snjxYo4dO2av/9NPP5GRkcHQoUMr/oM6kR7TAJkJ+0jNT0a8NcmOiIgUCAsL4z//+Q8Wi4U2bdqwefNm/vOf/9C/f39++OEH/vzzT/r06QPA559/TlhYGAsXLuTWW28957VfeuklHn/8ccaOHWsv69mzJwB9+vShTZs2fPbZZzz55JMAzJkzh1tvvfWCe9SjlhHAmriXlNOzr/p5+Dk5GhERqU4uueQSh7k0evfuze7du9m2bRtubm5ERETYj9WvX582bdqwffv2c143ISGBo0ePMmDAgGLr3HvvvcyZMweA+Ph4fvnlF+6+++7z+DTVk5IRwEg+QJqLkhEREak6+VOpl2TEiBHs27ePmJgY5s6dS3h4OH379q2C6KqWkhEgKzPRvu3v4e/ESEREpLpZs2aNw/7q1atp3bo17du3Jy8vz+H4iRMn2LlzJ+3btz/ndf38/GjevHmJQ33r16/PkCFDmDNnDh9//DGjRo0q/wepxtRnBMiypgDgYbji7uru5GhERKQ6iY2NZfz48dx///2sX7+et99+m3//+9+0bt2awYMHM3r0aN5//338/PyYOHEijRs3ZvDgwaW69vPPP88DDzxAcHAwAwcOJDU1lT///JNHHnnEXufee+/luuuuw2q1MnLkyMr6mE6lZATIsqYD4GNRIiIiIo5GjBhBZmYmvXr1wtXVlbFjx3LfffcBZofSsWPHct1115GTk0O/fv1YtGgR7u6l+z4ZOXIkWVlZ/Oc//2HChAkEBQVxyy23ONSJjIykYcOGdOjQgUaNLsxV5S1G/mDpaiwlJYWAgACSk5Px96/4xyhf/OcKptVLpKElkP+NWFHh1xcRkdLJyspi//79hIeH4+Xl/BXU+/fvT9euXZkxY4bTYkhLS6Nx48bMmTOHm266yWlxFKekn1lpv7/VMgJkkwlAHZdzdyYSERGpCjabjcTERP79738TGBjIDTfc4OyQKo2SESCbbADquNVxciQiIiKm2NhYwsPDadKkCR9//DFubhfuV/aF+8nKIIscwIU67hfWJDIiInJ+li9f7rT3bt68OTWgJ0WF0NBeINvFXLHXV8N6RUREqpySESDLYgXA3zPQuYGIiIjUQkpGbDYyXWwABPhoXRoREZGqVuuTESM7mdTT69IE+mrFXhERkapW65ORnNQTpLqYCyDVq6OWERERkapW65ORrJQTpJ5eJC/IJ8DJ0YiIiNQ+5UpGZs6cSfPmzfHy8iIiIoK1a9cWW/fDDz+kb9++1K1bl7p16xIZGVli/aqWk5ZIyulkJNBLyYiIiEhVK3MyMm/ePMaPH8+UKVNYv349Xbp0ISoqioSEhCLrL1++nNtvv53ffvuNmJgYwsLCuPrqqzly5Mh5B18R8tJO2ltG/Dz8nByNiIhI6RiGweTJk2nYsCHe3t5ERkaye/duZ4dVLmVORqZPn87o0aMZNWoU7du3Z9asWfj4+DB79uwi63/++ec89NBDdO3albZt2/Lf//4Xm81W4pLJ2dnZpKSkOLwqS3ZaIpmnkxF/zTMiIiI1xGuvvcZbb73FrFmzWLNmDXXq1CEqKoqsrCxnh1ZmZUpGcnJyWLduHZGRkQUXcHEhMjKSmJiYUl0jIyOD3Nxc6tWrV2ydadOmERAQYH+FhYWVJcwySc46ad+u467p4EVEqhvDMMjIyavyV1lnP127di19+/bFz8+POnXq0KlTJ/76669KuyczZszg2WefZfDgwXTu3JlPP/2Uo0ePsnDhwkp5z8pUpungExMTsVqthIQ4DoENCQlhx44dpbrGU089RaNGjRwSmrNNmjSJ8ePH2/dTUlIqLSFJzTJbXTxtLri5aHZ8EZHqJjPXSvvJv1b5+26bGoWPR+m/F4YNG0afPn344IMP8PLyYt++fYW+L8/0wAMPMHfu3BKvmZaWVmT5/v37iYuLc/guDQgIICIigpiYGIYNG1bquKuDKv32ffXVV/nqq69Yvnx5iUtDe3p64unpWSUxpealAuBtKBEREZHyy8vLo2nTprRq1Qp3d3fCw8NLrD916lQmTJhQrveKi4sDKLJxIP9YTVKmb+CgoCBcXV2Jj493KI+Pjyc0NLTEc9944w1effVVli5dSufOncseaSVJzU0HF/Ay3J0dioiIFMHb3ZVtU6Oc8r5lMX/+fG688UZee+01vLy8OHLkCAEBxY/SDA4OJjg4+HzDvCCUqc+Ih4cH3bt3d+h8mt8ZtXfv3sWe99prr/Hiiy+yePFievToUf5oK0G6NQMALzycHImIiBTFYrHg4+FW5S+LxVKmOCdNmkTPnj1ZtWoVGzZswM+v5BGaDzzwAL6+viW+ipPfAFCexoHqqMzPJsaPH8/IkSPp0aMHvXr1YsaMGaSnpzNq1CgARowYQePGjZk2bRoA//d//8fkyZP54osvaN68ub356Fw3uqpk2sxex55UzWMhERG58CQmJrJ06VI2bNhAly5dSnXO+TymCQ8PJzQ0lOjoaLp27QqY/SvXrFnDgw8+WK5rOlOZk5GhQ4dy/PhxJk+eTFxcHF27dmXx4sX251axsbG4uBQ0uLz33nvk5ORwyy23OFxnypQpPP/88+cXfQXIsmUD4OGiZERERMonKCiIsLAwJk+ezOTJkwkKCmL//v3k5ORw9dVXF3nO+TymsVgsjBs3jpdeeonWrVsTHh7Oc889R6NGjRgyZMh5fBLnKFevzTFjxjBmzJgijy1fvtxh/8CBA+V5iyqTa+QA4KZkREREzsMvv/zCxIkTiYqKIjU1laZNmzJ58uRKe78nn3yS9PR07rvvPpKSkrjssstYvHhxiQNEqqtaP4Qk18gFwN2l5v3wRESk+ujQoQM//vhjlb2fxWJh6tSpTJ06tcres7LU+oXyco08QMmIiIiIsygZwQqAh6u3kyMRERGpnZSMWE4nI25KRkRERJyh1icjOZhrDygZERERcQ4lIxYzGfFy93FyJCIiIrWTkpH8ZMRNyYiIiIgz1PpkJPv0bL9e7nWcG4iIiEgtVbuTEZuVnNNrD3h5qGVERETEGWp3MmLNIet0MuLjVfKCRiIiIlI5an0ykn06GanjqWRERETEGWp5MpJLlouSERERqXkMw2Dy5Mk0bNgQb29vIiMj2b179znPmzlzJs2bN8fLy4uIiAjWrl3rcPyDDz6gf//++Pv7Y7FYSEpKqqRPUKB2JyN52fbHNL6e6jMiIiI1x2uvvcZbb73FrFmzWLNmDXXq1CEqKoqsrKxiz5k3bx7jx49nypQprF+/ni5duhAVFUVCQoK9TkZGBtdccw1PP/10VXwMoLYnI2c8pvFXMiIiUj0ZBuSkV/3LMMoU5tq1a+nbty9+fn7UqVOHTp068ddff1XSLTGYMWMGzz77LIMHD6Zz5858+umnHD16lIULFxZ73vTp0xk9ejSjRo2iffv2zJo1Cx8fH2bPnm2vM27cOCZOnMgll1xSKbEXpVav2puZnY71dDLi56kZWEVEqqXcDHilUdW/79NHwaP00z4MGzaMPn368MEHH+Dl5cW+ffsICQkptv4DDzzA3LlzS7xmWlpakeX79+8nLi6OyMhIe1lAQAARERHExMQwbNiwQufk5OSwbt06Jk2aZC9zcXEhMjKSmJiYc328SlWrk5G07FT7tr+XWkZERKT88vLyaNq0Ka1atcLd3Z3w8PAS60+dOpUJEyaU673i4uIACiU7ISEh9mNnS0xMxGq1FnnOjh07yhVHRanVyUh6hpmMWAwDPw+1jIiIVEvuPmYrhTPetwzmz5/PjTfeyGuvvYaXlxdHjhwhICCg2PrBwcEEBwefb5QXhFqdjKSebhlxN8DNtXZ3nxERqbYsljI9LnGWSZMm0bNnTyZOnEi9evXw8yt5lOb5PKYJDQ0FID4+noYNG9rL4+Pj6dq1a5HnBAUF4erqSnx8vEN5fHy8/XrOUquTkYzsdAA8ytZHSURExEFiYiJLly5lw4YNdOnSpVTnnM9jmvDwcEJDQ4mOjrYnHykpKaxZs4YHH3ywyHM8PDzo3r070dHRDBkyBACbzUZ0dDRjxowpVxwVpVYnI+n2ZMTi5EhERKQmCwoKIiwsjMmTJzN58mSCgoLYv38/OTk5XH311UWecz6PaSwWC+PGjeOll16idevWhIeH89xzz9GoUSN7ogEwYMAAbrzxRnuyMX78eEaOHEmPHj3o1asXM2bMID09nVGjRtnPiYuLIy4ujj179gCwefNm/Pz8aNq0KfXq1StXvOdSq5ORzNwMQMmIiIicv19++YWJEycSFRVFamoqTZs2ZfLkyZX2fk8++STp6encd999JCUlcdlll7F48WK8vLzsdfbu3UtiYqJ9f+jQoRw/fpzJkycTFxdH165dWbx4sUOn1lmzZvHCCy/Y9/v16wfAnDlzuOuuuyrls1gMo4wDqZ0gJSWFgIAAkpOT8ff3r7DrfrPoRaYe/5qmOS78PHpjhV1XRETKJysri/379xMeHu7wpSrVV0k/s9J+f9fqXptZeZkAuKtlRERExGlqdTKSnWdOmetWu2+DiIiIU9Xqb+GcvGwA3IxafRtEREScqlZ/C+dYTycjFlcnRyIiIlJ71fJkJAcA19p9G0RERJyqVn8L59rMZMQNtYyIiIg4i5IRwK12T7ciIiLiVLU8GckF1GdERETEmWp1MpJn5AHgZnF3ciQiIiK1V+1ORvJbRlz0mEZERMRZancycrplxF0tIyIiUsMYhsHkyZNp2LAh3t7eREZGsnv37hLP+eOPP7j++utp1KgRFouFhQsXVk2w51DLkxErAO4uSkZERKRmee2113jrrbeYNWsWa9asoU6dOkRFRZGVlVXsOenp6XTp0oWZM2dWYaTnVqufT+ShZEREpLozDIPM02uJVSVvN28sltKvXbZ27Voef/xxNmzYgM1mo0WLFsyePZuePXtWeGyGYTBjxgyeffZZBg8eDMCnn35KSEgICxcuZNiwYUWeN3DgQAYOHFjh8ZwvJSOAm6uHkyMREZHiZOZlEvFFRJW/75o71uDj7lPq+sOGDaNPnz588MEHeHl5sW/fPkJCQoqt/8ADDzB37twSr5mWllZk+f79+4mLiyMyMtJeFhAQQEREBDExMcUmI9VVuR7TzJw5k+bNm+Pl5UVERARr164ttu7WrVu5+eabad68ORaLhRkzZpQ31gqXn4x4uHo6ORIREanp8vLyaNq0Ka1atSI8PJwBAwbQtGnTYutPnTqVDRs2lPgqTlxcHEChZCckJMR+rCYpc8vIvHnzGD9+PLNmzSIiIoIZM2YQFRXFzp07CQ4OLlQ/IyODFi1acOutt/LYY49VSNAVJQ8boGRERKQ683bzZs0da5zyvmUxf/58brzxRl577TW8vLw4cuQIAQEBxdYPDg4u8nuzNipzMjJ9+nRGjx7NqFGjAJg1axY///wzs2fPZuLEiYXq9+zZ0/68rKjjRcnOziY7O9u+n5KSUtYwS8V6OhnxVDIiIlJtWSyWMj0ucZZJkybRs2dPJk6cSL169fDz8yux/vk8pgkNDQUgPj6ehg0b2svj4+Pp2rVr2QKvBsqUjOTk5LBu3TomTZpkL3NxcSEyMpKYmJgKC2ratGm88MILFXa94ri6mx2TQgP8K/29RETkwpWYmMjSpUvZsGEDXbp0KdU5U6dOZcKECeV6v/DwcEJDQ4mOjrYnHykpKaxZs4YHH3ywXNd0pjIlI4mJiVit1iKfUe3YsaPCgpo0aRLjx4+376ekpBAWFlZh18/n4eWPe+5J6tYtvoORiIjIuQQFBREWFsbkyZOZPHkyQUFB7N+/n5ycHK6++uoizzmfxzQWi4Vx48bx0ksv0bp1a8LDw3nuuedo1KgRQ4YMsdcbMGAAN954I2PGjAHMlpY9e/bYj+/fv58NGzZQr169Evu3VLZqOZrG09MTT8/Kf3Qy547fK/09RESkdvjll1+YOHEiUVFRpKam0rRpUyZPnlxp7/fkk0+Snp7OfffdR1JSEpdddhmLFy/Gy8vLXmfv3r0kJiba9//++2+uuOIK+37+H/4jR47k448/rrRYz6VMyUhQUBCurq7Ex8c7lMfHx9ufX4mIiNRGHTp04Mcff6yy97NYLEydOpWpU6cWW+fAgQMO+/3798cwjEqOrOzKNLTXw8OD7t27Ex0dbS+z2WxER0fTu3fvCg9ORERELnxlfkwzfvx4Ro4cSY8ePejVqxczZswgPT3dPrpmxIgRNG7cmGnTpgFmp9dt27bZt48cOcKGDRvw9fWlVatWFfhRREREpCYqczIydOhQjh8/zuTJk4mLi6Nr164sXrzY3qk1NjYWF5eCBpejR49y8cUX2/ffeOMN3njjDS6//HKWL19+/p9AREREajSLUR0fHp0lJSWFgIAAkpOT8ffXMFwRkQtVVlYW+/fvJzw83KEjplRfJf3MSvv9XatX7RURkeqpBvydLKdVxM9KyYiIiFQb7u7mKuoZGRlOjkRKK/9nlf+zK49qOc+IiIjUTq6urgQGBpKQkACAj48PFovFyVFJUQzDICMjg4SEBAIDA3F1dS33tZSMiIhItZI/b1V+QiLVW2Bg4HnPNaZkREREqhWLxULDhg0JDg4mNzfX2eFICdzd3c+rRSSfkhEREamWXF1dK+SLTqo/dWAVERERp1IyIiIiIk6lZEREREScqkb0GcmfUCUlJcXJkYiIiEhp5X9vn2titBqRjKSmpgIQFhbm5EhERESkrFJTUwkICCj2eI1Ym8Zms3H06FH8/PwqdPKblJQUwsLCOHTokNa8qWS611VD97lq6D5XDd3nqlNZ99owDFJTU2nUqJHDIrpnqxEtIy4uLjRp0qTSru/v769/6FVE97pq6D5XDd3nqqH7XHUq416X1CKSTx1YRURExKmUjIiIiIhT1epkxNPTkylTpuDp6ensUC54utdVQ/e5aug+Vw3d56rj7HtdIzqwioiIyIWrVreMiIiIiPMpGRERERGnUjIiIiIiTqVkRERERJyqVicjM2fOpHnz5nh5eREREcHatWudHVKNMW3aNHr27Imfnx/BwcEMGTKEnTt3OtTJysri4Ycfpn79+vj6+nLzzTcTHx/vUCc2NpZBgwbh4+NDcHAwTzzxBHl5eVX5UWqUV199FYvFwrhx4+xlus8V58iRI/zrX/+ifv36eHt706lTJ/7++2/7ccMwmDx5Mg0bNsTb25vIyEh2797tcI2TJ08yfPhw/P39CQwM5J577iEtLa2qP0q1ZbVaee655wgPD8fb25uWLVvy4osvOqxdovtcPn/88QfXX389jRo1wmKxsHDhQofjFXVfN23aRN++ffHy8iIsLIzXXnvt/IM3aqmvvvrK8PDwMGbPnm1s3brVGD16tBEYGGjEx8c7O7QaISoqypgzZ46xZcsWY8OGDca1115rNG3a1EhLS7PXeeCBB4ywsDAjOjra+Pvvv41LLrnE6NOnj/14Xl6e0bFjRyMyMtL4559/jEWLFhlBQUHGpEmTnPGRqr21a9cazZs3Nzp37myMHTvWXq77XDFOnjxpNGvWzLjrrruMNWvWGPv27TN+/fVXY8+ePfY6r776qhEQEGAsXLjQ2Lhxo3HDDTcY4eHhRmZmpr3ONddcY3Tp0sVYvXq1sWLFCqNVq1bG7bff7oyPVC29/PLLRv369Y2ffvrJ2L9/v/HNN98Yvr6+xptvvmmvo/tcPosWLTKeeeYZY/78+QZgLFiwwOF4RdzX5ORkIyQkxBg+fLixZcsW48svvzS8vb2N999//7xir7XJSK9evYyHH37Yvm+1Wo1GjRoZ06ZNc2JUNVdCQoIBGL///rthGIaRlJRkuLu7G9988429zvbt2w3AiImJMQzD/B/HxcXFiIuLs9d57733DH9/fyM7O7tqP0A1l5qaarRu3dpYsmSJcfnll9uTEd3nivPUU08Zl112WbHHbTabERoaarz++uv2sqSkJMPT09P48ssvDcMwjG3bthmA8ddff9nr/PLLL4bFYjGOHDlSecHXIIMGDTLuvvtuh7KbbrrJGD58uGEYus8V5exkpKLu67vvvmvUrVvX4XfHU089ZbRp0+a84q2Vj2lycnJYt24dkZGR9jIXFxciIyOJiYlxYmQ1V3JyMgD16tUDYN26deTm5jrc47Zt29K0aVP7PY6JiaFTp06EhITY60RFRZGSksLWrVurMPrq7+GHH2bQoEEO9xN0nyvSDz/8QI8ePbj11lsJDg7m4osv5sMPP7Qf379/P3FxcQ73OiAggIiICId7HRgYSI8ePex1IiMjcXFxYc2aNVX3YaqxPn36EB0dza5duwDYuHEjK1euZODAgYDuc2WpqPsaExNDv3798PDwsNeJiopi586dnDp1qtzx1YiF8ipaYmIiVqvV4ZczQEhICDt27HBSVDWXzWZj3LhxXHrppXTs2BGAuLg4PDw8CAwMdKgbEhJCXFycvU5RP4P8Y2L66quvWL9+PX/99VehY7rPFWffvn289957jB8/nqeffpq//vqLRx99FA8PD0aOHGm/V0XdyzPvdXBwsMNxNzc36tWrp3t92sSJE0lJSaFt27a4urpitVp5+eWXGT58OIDucyWpqPsaFxdHeHh4oWvkH6tbt2654quVyYhUrIcffpgtW7awcuVKZ4dywTl06BBjx45lyZIleHl5OTucC5rNZqNHjx688sorAFx88cVs2bKFWbNmMXLkSCdHd+H4+uuv+fzzz/niiy/o0KEDGzZsYNy4cTRq1Ej3uRarlY9pgoKCcHV1LTTiID4+ntDQUCdFVTONGTOGn376id9++40mTZrYy0NDQ8nJySEpKcmh/pn3ODQ0tMifQf4xMR/DJCQk0K1bN9zc3HBzc+P333/nrbfews3NjZCQEN3nCtKwYUPat2/vUNauXTtiY2OBgntV0u+N0NBQEhISHI7n5eVx8uRJ3evTnnjiCSZOnMiwYcPo1KkTd955J4899hjTpk0DdJ8rS0Xd18r6fVIrkxEPDw+6d+9OdHS0vcxmsxEdHU3v3r2dGFnNYRgGY8aMYcGCBSxbtqxQs1337t1xd3d3uMc7d+4kNjbWfo979+7N5s2bHf7xL1myBH9//0JfCrXVgAED2Lx5Mxs2bLC/evTowfDhw+3bus8V49JLLy00PH3Xrl00a9YMgPDwcEJDQx3udUpKCmvWrHG410lJSaxbt85eZ9myZdhsNiIiIqrgU1R/GRkZuLg4fvW4urpis9kA3efKUlH3tXfv3vzxxx/k5uba6yxZsoQ2bdqU+xENULuH9np6ehoff/yxsW3bNuO+++4zAgMDHUYcSPEefPBBIyAgwFi+fLlx7Ngx+ysjI8Ne54EHHjCaNm1qLFu2zPj777+N3r17G71797Yfzx9yevXVVxsbNmwwFi9ebDRo0EBDTs/hzNE0hqH7XFHWrl1ruLm5GS+//LKxe/du4/PPPzd8fHyMuXPn2uu8+uqrRmBgoPH9998bmzZtMgYPHlzk0MiLL77YWLNmjbFy5UqjdevWtX7I6ZlGjhxpNG7c2D60d/78+UZQUJDx5JNP2uvoPpdPamqq8c8//xj//POPARjTp083/vnnH+PgwYOGYVTMfU1KSjJCQkKMO++809iyZYvx1VdfGT4+Phraez7efvtto2nTpoaHh4fRq1cvY/Xq1c4OqcYAinzNmTPHXiczM9N46KGHjLp16xo+Pj7GjTfeaBw7dszhOgcOHDAGDhxoeHt7G0FBQcbjjz9u5ObmVvGnqVnOTkZ0nyvOjz/+aHTs2NHw9PQ02rZta3zwwQcOx202m/Hcc88ZISEhhqenpzFgwABj586dDnVOnDhh3H777Yavr6/h7+9vjBo1ykhNTa3Kj1GtpaSkGGPHjjWaNm1qeHl5GS1atDCeeeYZh6Gius/l89tvvxX5e3nkyJGGYVTcfd24caNx2WWXGZ6enkbjxo2NV1999bxjtxjGGdPeiYiIiFSxWtlnRERERKoPJSMiIiLiVEpGRERExKmUjIiIiIhTKRkRERERp1IyIiIiIk6lZEREREScSsmIiIiIOJWSEREREXEqJSMiUunuuusuhgwZ4uwwRKSaUjIiIiIiTqVkREQqzLfffkunTp3w9vamfv36REZG8sQTT/DJJ5/w/fffY7FYsFgsLF++HIBDhw5x2223ERgYSL169Rg8eDAHDhywXy+/ReWFF16gQYMG+Pv788ADD5CTk+OcDygilcLN2QGIyIXh2LFj3H777bz22mvceOONpKamsmLFCkaMGEFsbCwpKSnMmTMHgHr16pGbm0tUVBS9e/dmxYoVuLm58dJLL3HNNdewadMmPDw8AIiOjsbLy4vly5dz4MABRo0aRf369Xn55Zed+XFFpAIpGRGRCnHs2DHy8vK46aabaNasGQCdOnUCwNvbm+zsbEJDQ+31586di81m47///S8WiwWAOXPmEBgYyPLly7n66qsB8PDwYPbs2fj4+NChQwemTp3KE088wYsvvoiLixp3RS4E+j9ZRCpEly5dGDBgAJ06deLWW2/lww8/5NSpU8XW37hxI3v27MHPzw9fX198fX2pV68eWVlZ7N271+G6Pj4+9v3evXuTlpbGoUOHKvXziEjVUcuIiFQIV1dXlixZwqpVq/jf//7H22+/zTPPPMOaNWuKrJ+Wlkb37t35/PPPCx1r0KBBZYcrItWIkhERqTAWi4VLL72USy+9lMmTJ9OsWTMWLFiAh4cHVqvVoW63bt2YN28ewcHB+Pv7F3vNjRs3kpmZibe3NwCrV6/G19eXsLCwSv0sIlJ19JhGRCrEmjVreOWVV/j777+JjY1l/vz5HD9+nHbt2tG8eXM2bdrEzp07SUxMJDc3l+HDhxMUFMTgwYNZsWIF+/fvZ/ny5Tz66KMcPnzYft2cnBzuuecetm3bxqJFi5gyZQpjxoxRfxGRC4haRkSkQvj7+/PHH38wY8YMUlJSaNasGf/+978ZOHAgPXr0YPny5fTo0YO0tDR+++03+vfvzx9//MFTTz3FTTfdRGpqKo0bN2bAgAEOLSUDBgygdevW9OvXj+zsbG6//Xaef/55531QEalwFsMwDGcHISJSlLvuuoukpCQWLlzo7FBEpBKpnVNEREScSsmIiIiIOJUe04iIiIhTqWVEREREnErJiIiIiDiVkhERERFxKiUjIiIi4lRKRkRERMSplIyIiIiIUykZEREREadSMiIiIiJO9f/7n5Da+4wMFgAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "colors = {\n",
    "    'ε = 0.1': 'tab:blue',\n",
    "    'ε = 0.01': 'tab:red',\n",
    "    'ε = 0': 'tab:green'\n",
    "}\n",
    "\n",
    "(\n",
    "    trace_df\n",
    "    .groupby(['step', 'policy'])\n",
    "    ['is_action_optimal'].mean()\n",
    "    .unstack()\n",
    "    .plot()\n",
    ")\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Handling drift"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The environment used above is a toy situation used for introducing bandits. It is stationary, meaning that the expected reward of each arm does not change over time.\n",
    "\n",
    "In practice, arms are dynamic, and their performance can vary over time. A simple example of this is the [Candy Cane Contest](https://www.kaggle.com/c/santa-2020) that was hosted on Kaggle in 2020. The expected reward of each arm diminishes each time it is pulled.\n",
    "\n",
    "The way bandit policies in River deal with drift depends on the method. For the `bandit.EpsilonGreedy` policy, it makes sense to use a rolling average as the reward object. What this means is that the empirical reward the policy calculates for each arm is a rolling average, rather than a global one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:48:30.255929Z",
     "iopub.status.busy": "2023-12-04T17:48:30.255815Z",
     "iopub.status.idle": "2023-12-04T17:48:42.028234Z",
     "shell.execute_reply": "2023-12-04T17:48:42.027755Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  0%|                                                                                                                                                                    | 0/180000 [00:00<?, ?it/s]/Users/max/Library/Caches/pypoetry/virtualenvs/river--dXL33ck-py3.11/lib/python3.11/site-packages/gym/utils/passive_env_checker.py:233: DeprecationWarning: `np.bool8` is a deprecated alias for `np.bool_`.  (Deprecated NumPy 1.24)\n",
      "  if not isinstance(terminated, (bool, np.bool8)):\n",
      "100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 180000/180000 [00:11<00:00, 15839.35it/s]\n"
     ]
    }
   ],
   "source": [
    "from river import proba, utils\n",
    "\n",
    "policies=[\n",
    "    bandit.EpsilonGreedy(\n",
    "        epsilon=0.1,\n",
    "        seed=42\n",
    "    ),\n",
    "    bandit.EpsilonGreedy(\n",
    "        epsilon=0.3,\n",
    "        reward_obj=utils.Rolling(stats.Mean(), window_size=50),\n",
    "        seed=42\n",
    "    ),\n",
    "    bandit.ThompsonSampling(\n",
    "        reward_obj=proba.Beta(),\n",
    "        seed=42\n",
    "    )\n",
    "]\n",
    "\n",
    "env = gym.make('river_bandits/CandyCaneContest-v0')\n",
    "\n",
    "trace = bandit.evaluate(\n",
    "    policies=policies,\n",
    "    env=env,\n",
    "    n_episodes=(n_episodes := 30),\n",
    "    seed=42\n",
    ")\n",
    "\n",
    "trace_df = pd.DataFrame(tqdm(\n",
    "    trace, position=0, total=(\n",
    "        n_episodes *\n",
    "        len(policies) *\n",
    "        env._max_episode_steps\n",
    "    )\n",
    "))\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can compare the performance of each policy by checking the average reward at the end of each episode."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:48:42.030198Z",
     "iopub.status.busy": "2023-12-04T17:48:42.030068Z",
     "iopub.status.idle": "2023-12-04T17:48:42.048400Z",
     "shell.execute_reply": "2023-12-04T17:48:42.048120Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "policy_idx\n",
       "0    736.1\n",
       "1    817.0\n",
       "2    854.0\n",
       "Name: reward_stat, dtype: float64"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(\n",
    "    trace_df\n",
    "    .groupby(['policy_idx', 'episode'])\n",
    "    .last()\n",
    "    .groupby('policy_idx')\n",
    "    .reward_stat.mean()\n",
    ")\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that using a rolling average gives a boost to the epsilon greedy strategy. However, we see that the `bandit.ThompsonSampling` policy performs even better, even though no particular care was given to drift. A natural next step would thus be to see how it could be improved to handle drift. For instance, its `dist` parameter could be wrapped with a `utils.Rolling`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-12-04T17:48:42.050015Z",
     "iopub.status.busy": "2023-12-04T17:48:42.049915Z",
     "iopub.status.idle": "2023-12-04T17:48:42.061196Z",
     "shell.execute_reply": "2023-12-04T17:48:42.060883Z"
    }
   },
   "outputs": [],
   "source": [
    "policy = bandit.ThompsonSampling(\n",
    "    reward_obj=utils.Rolling(proba.Beta(), window_size=50),\n",
    "    seed=42\n",
    ")\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Bandits can be used for several tasks. They can be used for content personalization, as well as online model selection (see `model_selection.BanditRegressor`). The policies in River are therefore designed to be flexible, so that they can be used in conjunction with other River modules. For instance, the `reward_obj` in `bandit.EpsilonGreedy` can be a metric, a probability distribution, or a statistic. This works because objects in River adher to a coherent get/update interface."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.12 ('river')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.0"
  },
  "vscode": {
   "interpreter": {
    "hash": "e6e87bad9c8c768904c061eafcb4f6739260ff8bb57f302c215ab258ded773dc"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
